burst-generate-files

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__",
                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__",
                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.

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

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

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.