Seamlessly generate template files with dynamic data.
Rubberstamp provides a simple way to copy template directories while modifying file names and contents.
- Simple, intuitive API
- Template-based case modification of variables
npm i rubberstamp
First, create template files in your source directory. For example:
src/
├─ index.js
├─ templates/
│ ├─ __name__.js.template
│ ├─ package.json.template
// templates/__name__.js.template
export const __name__ = () => {
return console.log('Hello! My name is __name__');
};
// templates/package.json.template
{
"name": "component-__name__",
"main": "__name__.js"
}
Then, use the stamp()
function to clone the templated directory and populate the files with the provided variables.
// index.js
import { stamp } from '@mattiebear/rubberstamp';
const name = 'hello';
const source = './templates';
const destination = `./packages`;
const inject = { name };
const copyTemplate = async () => {
await stamp(source, destination, { inject });
};
copyTemplate();
This will create modifed fields in the specified directory. In this case, everything in the templates
directory and its child directories will be transferred and modified to a newly created packages
directory.
// packages/hello.js
export const hello = () => {
return console.log('Hola! My name is hello');
};
// packages/package.json
{
"name": "component-hello",
"main": "hello.js"
}
Super simple!
stamp()
accepts a single configuration object.
name | required | type | description |
---|---|---|---|
source |
yes | string | The file path location of your template files. stamp will recursively transfer all files in this directory. |
destination |
yes | string | The location to which all files from source will be transferred while maintaining directory structure. |
inject |
no | Record<string, string> | An object of key value pairs denoting the variables to inject into file/directory names and content. |
copyPattern |
no | string, RegExp, Array<string, RegExp> | Pattern of files to copy directly |
ignorePattern |
no | string, RegExp, Array<string, RegExp> | Pattern of files or directories to ignore from cloning |
You can alter the names of files and directories as well as the contents when injection tokens are included in either. To modify the name of a file or directory, include the format __name__
in the filename, that is the key of the variable bookended by double underscores. Rubberstamp will replace instances of __name__
with the { name: 'value' }
entry in the injection object.
Note that you do not need to append .template
to the end of file names but it is recommended so IDEs do not treat the files as syntactically invalid. Any .template
suffix will be automatically removed from file names but are not required.
When a file is populated with variable data it's often necessary to change the case of the passed string variables. One way to do this is to declare multiple variables and pass them in the inject
option:
const inject = {
name: 'hello world',
nameCapital: 'Hello World',
namePascal: 'HelloWorld',
nameCamel: 'helloWorld',
};
This can be especially tedious with a large number of variables. Instead, Rubberstamp allows for case modifications within injection tokens. Simply include $
and the case modifier after the token name.
// templates/__name$K__.tsx.template
import { React } from 'react';
export const __name$P__ = () => { // convert to PascalCase
return <div>I am __name$C__<div> // convert to Capital Case
}
Assuming the provided injections { name: 'my component' }
the file would be modified to the following:
// packages/my-component.tsx
import { React } from 'react';
export const MyComponent = () => {
return <div>I am My Component<div>
}
Valid case modifiers are
case | token | example |
---|---|---|
camel | M | helloWorld |
capital | C | Hello World |
kebab | K | hello-world |
pascal | P | HelloWorld |
snake | S | hello_world |
Note that both lower and upper case tokens are value, i.e. __name$m__
and __name$M__
are identical.
The ignorePattern
config options allows you to pass in a list of strings or regular expressions that can be use to ignore a file or directory from cloning. If the resource is a directory any subdirectories or files within it will not be copied.
await stamp(source, destination, {
ignorePattern: ['node_moodules', new RegExp('ignore')],
});
By default a selection of files (ex images and audio) are expempt from the standard process of opening and re-writing the file contents to ensure file operability; the file extension is checked against a simple regex list. You can modify the check with the copyPattern
config option. These files will be copied with the copyFile
directive rather than writeFile
. The default list can be accessed via the copyPattern
import.
import { copyPattern } from '@mattiebear/rubberstamp';
await stamp(source, destination, {
copyPattern: [...copyPattern, '.template', '.ogg'],
});