1 unstable release
0.1.2 | May 25, 2020 |
---|
#44 in #handlebars
19KB
320 lines
Stamp
A command line tool for creating one or more files from templates, written in Rust.
Stamp was born out of a lack of tooling that filled this middle ground:
- IntelliJ supports creating files from templates, but only one file at a time.
- Tools like Cookiecutter and Yeoman are slow and far too large for quick usage.
Installation
You will require rust and cargo installed.
cargo install stampr
Annoyingly the crate name stamp
was already taken.
You might want to alias=stamp=stampr
.
Usage
Command Line Usage
Command line help can be viewed using stampr -h
or stampr --help
for more detail.
You can also use stampr help <command>
.
List
stampr list
will show a list of installed templates.
Passing the -v
flag will also show the path of each template on disk.
Run
stampr run <template>
will render a template and create the files.
By default, files are written relative to your current working directory.
To change this, use -o
or --out
.
If the path does not exist, it will be created for you.
Arguments for a template can be specified using the -c
or --context
flag,
and provided in key=value
pairs.
Any arguments not provided will prompt you for input.
This must be the last flag provided.
Example:
stampr run test --out /tmp/stamp-test -c greeting=Hello subject=World
Creating Templates
Locations
Templates can be stored globally or inside a directory. When looking for templates, Stamp will:
- Look for a
.stamp/templates
folder inside the current directory - Recurse up each parent directory, looking for the same folder
- Check the global directory
If multiple templates of the same name exist, the first one found is used. This means it is possible to include templates in your repository, and to override global templates by creating one of the same name inside a folder.
Global templates are stored inside the current user's configuration folder.
- Linux:
~/.config/stamp/templates
- OSX:
$USER/Library/Preferences/stamp
- Windows:
%appdata%\stamp\templates
Files
To create a template, simply create a directory with the template name in a templates folder.
Each file and folder inside that directory is then templated. The file name and contents are rendered using Handlebars. A number of helpers are available, and the list can be found here.
Variables used in templates are automatically detected and turned into arguments at runtime.
Example
One such use-case might be to scaffold out a single TypeScript React component, including a file for the props and another for the stylesheet.
The end goal is to end up with this structure:
testComponent
├── ITestComponentProps.ts
├── TestComponent.module.scss
└── TestComponent.tsx
To create the template, create a folder called tsx-component
in a Stamp template folder.
Inside the template folder, create a new folder to house the component files.
Name it {{to_camel_case name}}
.
This means the directory will always take the name argument and ensure it is in camelCase.
Inside that directory, create three files:
{{to_pascal_case name}}.tsx
I{{to_pascal_case name}}Props.ts
{{to_pascal_case name}}.module.scss
The first file houses imports for the other two, as well as a basic functional component:
import * as React from 'react';
import I{{to_pascal_case name}}Props from './I{{to_pascal_case name}}Props';
import styles from '{{to_pascal_case name}}.module.scss';
const {{to_pascal_case name}}: React.FC<I{{to_pascal_case name}}Props> = () => {
return <span />;
};
export default {{to_pascal_case name}};
The second contains a blank interface:
interface I{{to_pascal_case name}}Props {
}
export default I{{to_pascal_case name}}Props;
And the third can remain empty.
Now run your template:
stampr run tsx-component -c name=testComponent
You should see a directory created called testComponent
with 3 files inside.
Note it would be possible to avoid using the helpers above and just use
{{name}}
if you do not want causing to automatically be adjusted.
Dependencies
~6–13MB
~154K SLoC