Welcome to burst-generate-files.

This is a library for generating files and folders based on templates that the user creates.

How to install

Using npm:

npm i burst-generate-files

Fast instructions for use

Below are the steps we will take to build our first generation together.

Create your first template

Template is a folder with any structure. In our case, we create a simple example of React component.

Create the folder componentTemplate, then create file with name index.tsx, but also you can use another name __exampleComponentName__(pascalCase).tsx, in second variant we have dynamic file name with different replace modes. More information about variables in file names and replace modes you can find deeper in these docs.

// ./componentTemplate/index.tsx

import React from "react";

export const __exampleComponentName__(pascalCase) = () => {
    return (
        <div>
            This is component: __exampleComponentName__
        </div>
     );
};

Create config file

Let's create generate.config.ts in the root of your project.

First of all you need to add import of burst-generate-files, and get CLIGen function.

That function require one parameter, array of settings.

// ./generate.config.ts

import { CLIGen } from "burst-generate-files";

CLIGen([
    {
        name:      "Generate new React component",
        templates: [
            {
                stringsReplacers: "__exampleComponentName__",
                pathToTemplate:   "./componentTemplate",
                outputPath:       "./components/__exampleComponentName__(pascalCase)",
            },
        ],
    },
]);

If you happy with TypeScript

To start generating files, you need to run generate.config.ts, the best way to do this install ts-node package globally.

In terminal, you need just type next command and magic begin...

ts-node "./generate.config.ts"

Note: also you can add new script in your package.json, for example

"scripts": {
    "gen": "ts-node ./generate.config.ts"
},

If you must use JavaScript

For JavaScript all easier, in your terminal run next command:

node "./generate.config.js"

Command Line Interface

After running generate.config.js, advanced CLI started in your terminal. Next you have to choose that you want to generate, for example it will be Component. Press Enter to submit your choice, and continue.

On next step we need to type the name of entity what we are generating. All strings inside templates what you use, and looks like this: __entityName__, will replace with your name of entity.

For example, the name of the entity will be wrapper. Let's press Enter button to complete generation.

Finely, example React component file structure will be successfully created.

Congratulations, we make our first generation together!

Advanced use

Next, we will get acquainted with the main features of the library.

Variables in file or folder names

The library supports the syntax of variables in the names of files or folders that are contained in templates.

For example, we can rename index.tsx file in previous example to __exampleComponentName__(pascalCase).__exampleExtension__. In that case, name and extension of file will be replaced, by variables what are configured in config file. Let's add new variable to generate.config.ts file:

    // ./generate.config.ts
    {
        // ...
        stringsReplacers: [  // <= Open new array
            "__exampleComponentName__",
            "__exampleExtension__", // <= New variable here
        ],
        // ...
    }

Run generate.config.ts with new changes. In CLI add value wrapper to __exampleComponentName__, and add value tsx to __exampleExtension__, and get result with custom file name, and custom extension.

Extend template

Size of file structure no matter for burst generation. You can create any template, with any files and folder inside. For example, let's add new file in componentTemplate, and it will be styles.__exampleStyleExtension__.

    // ./generate.config.ts
    {
        // ...
        stringsReplacers: [
            "__exampleComponentName__",
            "__exampleExtension__",
            "__exampleStyleExtension__" // <= New variable again here
        ],
        // ...
    }

As result, we get new generated file structure based on extended template.

Extend config with new template

The library can support unlimited templates at the same time. For extend your config with new template, you need to create new template folder with some stuff inside, and add new settings object to generate.config.ts.

// ./generate.config.ts

CLIGen([
    {
        name:      "Generate new React component",
        templates: [
            {
                stringsReplacers: [
                    "__exampleComponentName__",
                    "__exampleExtension__",
                    "__exampleStyleExtension__",
                ],
                pathToTemplate:   "./componentTemplate",
                outputPath:       "./components/__exampleComponentName__(pascalCase)",
            },
        ],
    },
    {
        // <= Page generation config
        name:      "New page",
        templates: [
            {
                stringsReplacers: "__pageName__",
                pathToTemplate:   "./pageTemplate",
                outputPath:       "./page/__pageName__(pascalCase)",
            },
        ],
    },
]);

Markers

The main feature of this library is markers that you can put in existing files and add new lines. For example, a new line can be any entity, for example we use a usual import which should look like this import { Wrapper2 } from "./Wrapper2"; after using generate.

Foremost, we have to create the template for the marker. In the folder componentTemplate we have to create the folder .genignore, this folder is ignored during generation, we can store our marker in it. Let's name this file imports.ts.

Then we write the usual import, but we will use __exampleComponentName__ variable.

// ./componentTemplate/.genignore/import.ts

import { __exampleComponentName__(pascalCase) } from "./__exampleComponentName__(pascalCase)";

Next, create the file index.ts in the folder components. Then write the marker // Imports. You can write any name for marker and use multitude markers for generation.

In generate.config.ts we have to add the new key markers for our config generate.

// ./generate.config.ts

CLIGen([
    {
        name:      "Generate new React component",
        templates: [
            {
                stringsReplacers: [
                    "__exampleComponentName__",
                    "__exampleExtension__",
                    "__exampleStyleExtension__",
                ],
                pathToTemplate: "./componentTemplate",
                outputPath:     "./components/__exampleComponentName__(pascalCase)",
                markers: [
                    // <= New key here
                    {
                        pattern:        "// Imports",
                        pathToMarker:   "./components/index.ts",
                        markerTemplate: "./componentTemplate/.genignore/import.ts",
                    },
                ],
            },
        ],
    },
]);

And funnily, run the command ts-node "./generate.config.ts". After generation, we get new line like import.

Select a directory for generation

Also we can select a directory where we want to generate files. To activate this feature we have to remove outputPath. Then we have to run generate and fill inputs. After we can select a directory.

Note: if outputPath is removed, the current directory starts from the root project.

First the ../ option to climb to the top directory. Second the ./ option to generate files in current directory. Third the # Create new folder option to create new folder. And other options are folders in current directory.

For example, we can select the option /components. After, we entered the components folder.

Then, we can generate files in the components folder, but we have to create new folder, we have to select the # Create new folder option.

Then, we have to select the # Create new folder by stringsReplacers option. We can create new folder by stringsReplacers.

We have to select the /__exampleComponentName__ option.

Then, we can select type of string replacements. We have to select the pascalCase option.

Then we have to select the ./ option to generate the files. But we can continue to select a directory.

Finally, we generated the files.

Select a directory with the outputPath for generation

We can use the selectDirectory with the outputPath. For example, we can write:

// ./generate.config.ts

CLIGen([
    {
        name:      "Generate new React component",
        templates: [
            {
                stringsReplacers: [
                    "__exampleComponentName__",
                    "__exampleExtension__",
                    "__exampleStyleExtension__",
                ],
                pathToTemplate:  "./componentTemplate",
                outputPath:      "./components/__exampleComponentName__(pascalCase)",
                selectDirectory: true, // <= New key here
                markers: [
                    {
                        pattern:        "// Imports",
                        pathToMarker:   "./components/index.ts",
                        markerTemplate: "./componentTemplate/.genignore/import.ts",
                    },
                ],
            },
        ],
    },
]);

After ran generation, the path starts by the outputPath

Ultra plus use

If you want to look difficult cases with burst-generate-files. You can install Burst template. After install, you have to use script npm run gen in your terminal.

Settings

name

This is the name that will be displayed in the interface. For only the function CLIGen.

templates

This is array for settings to generate files. For only the function CLIGen.

stringsReplacers

This is the string or array with strings which will replace. But if you use the function customGen, then stringsReplacers is object or array, example:

// If you use the customGen

stringsReplacers: [
    {
        replaceVar: "__exampleComponentName__",
        value:      "Wrapper",
    },
    {
        replaceVar: "__exampleComponentName2__",
        value:      "Wrapper2",
    },
],

Types of string replacements

__componentName__(noCase) === lorem Lorem lorem
__componentName__(camelCase) === loremLorem
__componentName__(pascalCase) === LoremLorem
__componentName__(constantCase) === LOREM_LOREM
__componentName__(kebabCase) === lorem-lorem
__componentName__(dotCase) === lorem.lorem
__componentName__(lowerCase) === loremlorem
__componentName__(pathCase) === lorem/lorem
__componentName__(sentenceCase) === Lorem lorem
__componentName__(snakeCase) === lorem_lorem
__componentName__(titleCase) === Lorem Lorem
__componentName__ === loremLorem

pathToTemplate

This is the path or array with your paths for your template that will create.

outputPath optional

This is the path or array with your paths for output files.

selectDirectory optional

This is the boolean. Dynamic change your path.

Note: default value false.

markers optional

This is the array to create lines into files.

• pattern

  This is the marker for insert line. If you want, you can use any regular expressions like this pattern: /^.*(//.Marker)$/.

• pathToMarker

  This is the path or array with your paths to the file to insert your lines.

• markerTemplate

  This is path or paths to data of file to be inserted where is the pattern.

Note: for keeping and ignoring markers template, you have to create the folder .genignore.

• genDirection optional

  This is the option tells the program where to insert the line. Insert line after or before your pattern.

Note: if not exists, then default value after.

• onceInsert optional

  This is the boolean. If it is true, the row will only be inserted once, when you insert again you will catch the warning.

Note: if you want to paste again, you need edit file config.generate.files.json

onComplete optional

This is the function that will be executed after generation. If you want you can get the setting that was use. To get the object you need to use a callback.

onComplete: (obj) => {
    console.log(obj);
},

Optional settings

CLIGen(
    [
        // ...
        {
            name:      "Generate new React component",
            templates: [
                // ...
            ],
        },
        // ...
    ],
    {
        // <= Optional settings here
    }
);

rootPath optional

This is the string for changing root path of your project.

showFullError optional

This is the string for showing full message of error.

License

Apache 2.0 License