@scaffdog/types v4.1.0

scaffdog

Multiple files can be output in a document, and flexible scaffolding is possible with a simple but powerful template syntax :dog2:

Table of Contents

• :dog: Features
• :feet: Getting Started
• :bellhop_bell: Requirements
  • Installation
  • Quick Start
• :fire: Migration
• :wrench: Configuration
  • Simple Configuration
  • Global Variables
  • Custom Helpers
• :poodle: Commands
  • scaffdog init
  • scaffdog generate
  • scaffdog create
  • scaffdog list
• :memo: Templates
  • Structure
  • Syntax
  • Pipe chain
  • Attributes
  • Variables
  • Helpers
• :blue_book: FAQ
• :dog2: Contributing
  • Development scripts
• :gem: License

Features

• :pencil: Markdown driven
  • You can define a template with <h1> and code block.
  • It will be a Documetable template !
  • Define meta information with extended syntax using Front Matter.
• :hammer_and_pick: Simple & Powerful template syntax
  • A simple syntax similar to mustache.js. ({{ inputs.value }})
  • Function execution similar to pipe syntax. ({{ inputs.value | fn }})
  • Provide minimum necessary functions in built-in.
• :rocket: Ready to use
  • You can quickly start using $ scaffdog init.

Requirements

• Node.js v12.10 +

Getting Started

Installation

scaffdog can be installed globally, but we recommend installing it locally on the project.

$ npm install --save-dev scaffdog

Quick Start

In the following tutorial you can start using scaffdog immediately !

Setup

By default, it stores the document file and configuration file in the .scaffdog directory.

Creating directories, configuration file and initial documents can be done with the init subcommand.

$ npx scaffdog init

? Please enter a document name. hello

Setup of scaffdog 🐶 is complete!

  ✔ .scaffdog/config.js
  ✔ .scaffdog/hello.md

Now you can do scaffold by running `$ scaffdog generate`.

Please refer to the following documents and customize it.
https://github.com/cats-oss/scaffdog/#templates

After running the command, the .scaffdog/hello.md file should have been generated.

Let's scaffold using the hello document!

$ npx scaffdog generate hello

? Please select the output destination directory. .
? Please enter any text. pretty-dog

🐶 Generated 1 file!

     ✔ pretty-dog.md

Congratulations :tada:

The first file was generated.

$ cat pretty-dog.md

Let's make a document! See more detail scaffdog repository.
https://github.com/cats-oss/scaffdog/#templates

Please refer to this document and customize the document file :+1:

Migration

There are important changes in the major update.

• To v1 from v0

See Migration Guide.

Configuration

scaffdog uses the object exported in .scaffdog/config.js as the configuration.

Simple Configuration

In the files field, specify the path pattern of the document used by scaffdog. The files field is required.

module.exports = {
  files: ['./*'],
};

Global Variables

You can define the global variables available in the template in the variables field.

module.exports = {
  files: ['./*'],
  variables: {
    key: 'value',
  },
};

Custom Helpers

You can define the custom helpers available in the template in the helpers field.

module.exports = {
  files: ['./*'],
  helpers: [
    // Using Key-Value
    {
      trim: (context, value) => value.trim(),
    },

    // Using Helper Registry
    (registry) => {
      registry.set('padstart', (context, value, size, str) =>
        value.padStart(size, str || ' '),
      );
      registry.set('padend', (context, value, size, str) =>
        value.padEnd(size, str || ' '),
      );
    },
  ],
};

The context passed to the first argument of the helper function has the following structure.

type Variable =
  | string
  | {
      [key in string | number]: Variable;
    }
  | Variable[];

type VariableMap = Map<string, Variable>;

type Helper = (context: Context, ...args: any[]) => string;

type HelperMap = Map<string, Helper>;

type Context = {
  cwd: string;
  variables: VariableMap;
  helpers: HelperMap;
};

Commands

scaffdog init

Prepare to use scaffdog. Create a .scaffdog directory by default, and create a first document file.

Options:
  -p, --project  Directory to load the scaffdog project.        [string] [default: ".scaffdog"]
  -v, --verbose  Enable logging.                                                      [boolean]
      --help     Show help                                                            [boolean]
      --version  Output the version number                                            [boolean]

scaffdog generate

Build a scaffold using the specified template. If you do not specify the template name and execute it, interactively select the template.

Positionals:
  name                                                                                 [string]

Options:
  -p, --project  Directory to load the scaffdog project.        [string] [default: ".scaffdog"]
  -v, --verbose  Enable logging.                                                      [boolean]
      --help     Show help                                                            [boolean]
      --version  Output the version number                                            [boolean]
  -n, --dry-run  Output the result to stdout.                                         [boolean]

scaffdog create

Create a document file with the specified name.

Positionals:
  name  Specify a document file name.                                                  [string]

Options:
  -p, --project  Directory to load the scaffdog project.        [string] [default: ".scaffdog"]
  -v, --verbose  Enable logging.                                                      [boolean]
      --help     Show help                                                            [boolean]
      --version  Output the version number                                            [boolean]
  -y, --yes      Use default options.                                                 [boolean]

scaffdog list

Print a list of available documents.

Options:
  -p, --project  Directory to load the scaffdog project.        [string] [default: ".scaffdog"]
  -v, --verbose  Enable logging.                                                      [boolean]
      --help     Show help                                                            [boolean]
      --version  Output the version number                                            [boolean]

Templates

Structure

Template documents are defined with <h1> and code blocks. <h1> is interpreted as the file name and code blocks as the template body.

Meta information is defined using Front Matter.

---
name: 'utility'
root: 'src/utils'
output: '**/*'
ignore: []
questions:
  name: 'Please enter a filename.'
---

# `{{ inputs.name }}.js`

```javascript
export const {{ inputs.name | camel }} = () => true;
```

# `__tests__/{{ inputs.name }}.test.js`

```javascript
import { {{ inputs.name | camel }} } from '../{{ inputs.name }}';

describe('{{ inputs.name | camel }}', () => {
  test('__TODO__', () => {
    expect({{ inputs.name | camel }}()).toBe(true);
  });
});
```

Syntax

Between {{ and }} is interpreted as a tag. Whitespace in tag contents is ignored.

Output of variable

The given variable name is output. See the Variables section for the variables that can be used.

{{ <identifier> }}

Example:

{{ inputs.value }}

Whitespaces

Trim the expression to be expanded and the space and line feed around it.
Use {{- to trim before the tag, and -}} to trim after the tag.

{{- <expression> -}}

Example:

before {{- "text" }} after
before {{ "text" -}} after
before {{- "text" -}} after

Output:

beforetext after
before textafter
beforetextafter

Comment out

You can use comment out to keep the template readable. Of course, it is not deployed as a template.

{{ /* a comment */ }}

Call helper function

Execute the helper function with the specified name. Arguments are separated by whitespace. See the Helpers section for the helpers that can be used.

{{ <helper> <argument> ... }}

Example:

{{ relative "../" }}

Pipe chain

You can chain output values or helper results with pipes. This is a helper similar to shell.

{{ <identifier> | <helper> }}
{{ <identifier> | <helper> <argument> ... }}

Example:

{{ inputs.value | upper }}
{{ inputs.value | replace "$.ts" ".js" | pascal }}
{{ basename | replace extname ".js" | pascal }}

Attributes

List of attributes that can be specified with Front Matter.

questions defines the question to be used in prompt with key-value. The values you answer can be used in a variable called inputs. (e.g. inputs.key1, inputs.value)

---
questions:
  # Shortest syntax, using `input` prompt.
  key1: 'Message'

  # Using `input` prompt.
  key2:
    message: 'Message'

  # Using `input` prompt, with default value.
  key3:
    message: 'Message'
    initial: 'Initial Value'

  # Using `list` prompt.
  key4:
    message: 'Message'
    choices: ['A', 'B', 'C']
---

Variables

List of variables available in the template. You need to be aware that the file name and the variables available in the template body are different.

File name

Template body

Helpers

When invoked on a pipe, the previous processing result is passed to the first argument.

FAQ

scaffdog does not support variable definitions syntactically.

However, it is possible to define variables in combination with helper functions :tada:

See the following example.

{{- output.path | replace "^src/" "" | define "out" -}}
{{ output.path }}
{{ out }}
{{ out | replace "/" "-" }}

The output is as follows:

src/utils/input.js
utils/input.js
utils-input.js

Defined a variable called out which is a processed version of output.path. This is made up of some magic.

1. Save the calculation result to out with define helper function.
2. The variable definition tag trims whitespaces. (use {{- and -}})

Contributing

We are always welcoming your contribution :clap:

1. Fork (https://github.com/cats-oss/scaffdog) :tada:
2. Create a feature branch :coffee:
3. Run test suite with the $ yarn test command and confirm that it passes :zap:
4. Commit your changes :memo:
5. Rebase your local changes against the canary branch :bulb:
6. Create new Pull Request :love_letter:

Bugs, feature requests and comments are more than welcome in the issues.

Development scripts

yarn test

Run Unit test with ava.

$ yarn test

yarn lint

Run lint with ESLint.

$ yarn lint

yarn format

Run formatting with ESLint (--fix) and Prettier.

$ yarn format

License

MIT © Cyberagent, Inc