@lukasbach/scaffold NPM

Scaffold CLI

A templating tool for building reusable and configurable code templates in a central place.

Scaffold CLI Demo

How to use

Install the package

npm i -g @lukasbach/scaffold

You can get started by adding the official react templates to the global template scope, and creating a react FC file:

scaf add lukasbach/scaffold-cli/templates/react
scaf react-fc "My Component Name"

If you want to further customize how the template works, you could

Provide additional parameters:

scaf react-fc "My Component Name" --propsType inline --propsWithChildren false

Require scaffold to interactively ask for all parameters:
```
scaf react-fc --all
```

Create an alias or redefinition of an existing template with custom config values:

scaf customize react-fc -g
scaf edit-config

Adds a custom template overwrite such as:

templates:
  react-fc:
    source: ./templates/react/react-fc
    defaults:
      componentName: My Component
      dummyProp: false
      exportPropsType: true
      importReactSymbols: false
      propsType: type
      propsWithChildren: true
      deconstructProps: true
      filenameCase: paramCase
      fileExtension: tsx
    omitActions:
      - tsFormat
    postActions:
      - eslint

You can not only add and redefine templates globally, but also scoped to specific projects on your disk. Run

scaf init

in your project repository to create a scaffold config file and from there on customize templates scoped to your repository.

Available Templates

To add a template to the current scope, run scaf add githubuser/reponame/path/to/templaterepo. This will add the available templates to the nearest .scaf.yml. You can add --global to add it to your user config.

Generally, all parameters are optional when running a parameter. Parameters below marked with [--param] will use preset default values if not provided, parameters marked with --param will ask the user in an interactive prompt for the intended value before evaluating the template.

You can customize the default values for any template with scaf customize template-name [--global].

Core Templates

The following templates are core commands which are available by default.

Add Template Repo: Add a template repository to the template scope
scaf add <repo> [-g,--global]
Customize Template: Customize the default values for a template that is available in the current scope
scaf customize <template> [-g,--global]
Edit Config: Edit global Scaffold Config file scoped to the local user
scaf edit-config
Initialize: Initialize a scaffold config on a code repository
scaf init --addToReadme --defaultRepos=#
List templates: List all available templates
scaf list
Create Snapshots: Create snapshot dumps for all scaffold templates in a template repository.
scaf scaf-snap --repo=# [--output=#] [--failOnChange]
Update templates: Update local template repositories
scaf update

React Templates

The following templates are available in the template scope when adding the lukasbach/scaffold-cli/react template repository.

React Context: A React context instance with context provider, hook and context type
scaf react-context <ctxName> [--propsTypeSuffix=#] [--contextVariableSuffix=#] [--fileExtension=#] [--placeTypeInDedicatedFile] [--placeHookInDedicatedFile] [--placeProviderInDedicatedFile] [--exportPropsType] [--dummyProp] [--importReactSymbols] [--deconstructProps] [--propsType=#]
React FC: React Functional Component
scaf react-fc <componentName> [--dummyProp] [--exportPropsType] [--importReactSymbols] [--propsType=#] [--propsWithChildren] [--deconstructProps] [--filenameCase=#] [--fileExtension=#]
React Forwarded Ref: React Component with forwarded ref
scaf react-forward-ref <componentName> [--elementType=#] [--innerRef=#] [--includeUseRef] [--includeUseImperativeHandle] [--dummyProp] [--exportPropsType] [--importReactSymbols] [--propsType=#] [--propsWithChildren] [--deconstructProps] [--filenameCase=#] [--fileExtension=#]

Writing your own templates

Setting up your template repository

Within your repository, create a folder, let's name it "templates", and in there, create the files scaffold-templates.yml and my-template.ts.

my-repo/
  templates/
    scaffold-templates.yml
    my-template.ts
    my-other-template.ts
    my-template-with-assets/
      template.ts
      some-asset.json
  [.scaf.yml]

The scaffold-templates.yml file should contain the following content:

name: My Templates
description: Description Text
author: Lukas Bach
key: templates-key

We will look into how the template code looks like in the next section. There are multiple ways how to make the templates available:

If you want them available within your project, add and edit the .scaf.yml file mentioned in the file tree above in the top level of your project with the following content:
```
repositories:
- ./templates
```
You can also add more template repositories, either from your own machine or remotely.
If you want them available everywhere on your machine, add the Yaml code above to ~/.scaf.yml. You can edit that file by running scaf edit-config.
If you want them available on other machines, or publish them for other developers to use, create a git repository from your project, and push it to gh-user-name/my-repo. Then, use the following yaml code in a .scaf.yml file to reference the templates:
```
repositories:
- gh-user-name/my-repo/templates
```
This will automatically pull the repo when calling the template. The repo can be private, but needs to be pullable by your local git installation.

Writing a template

This is an example for a template implementation:

// Import is optional and provides type-safety for scaffold library.
// Install "@lukasbach/scaffold" as dev dependency in your project for that.
import "@lukasbach/scaffold/globals"

export default async () => {
  const sdk = scaffold.sdk().withDefaultCapabilities().build();
  sdk.setTemplateName("React FC");
  sdk.setTemplateDescription("React Functional Component");
  
  const componentName = await sdk.param
    .string("componentName")
    .asArgument()
    .default("My Component")
  
  // custom side effects like fs operations should be wrapped in sdk.do()
  await sdk.do(async () => {
    // Some packages like fs-extra, execa (as $), yaml, os or git are available
    // in global scope
    const v = (await fs.readJSON("package.json")).version
  });
  
  // Accessible in templates via {{ myData.packageJson.version }}
  sdk.setDataProperty("myData.packageJson.version", v)
  
  // Apply handlebars template and add file to fs
  // SDK-related functions are internally wrapped and don't explicitly need to
  // be wrapped with sdk.do()
  await sdk.actions.addFile("{{ camelCase componentName }}", "component.ts.hbl")
}

If your template just consists of code, you can add this code to templates/my-template.ts. If you want to add additional files like the component.ts.hbl file referenced above, add your template code to templates/my-template/template.ts.

You can use handlebar templates in template files used by scaffold, so templates/my-template/component.ts.hbl could look like that:

/** template version v{{ myData.packageJson.version }} */
const {{ pascalCase componentName }} = () => <div />;

You can look into official templates in the /templates folder for more examples.

Running your template

Once the template is added to your .scaf.yml and you finished the code, just run scaf my-template. You don't need to build anything, scaffold will compile your template on the fly.

Customizing existing templates

In your .scaf.yml file, you can customize existing templates by predefining parameters:

repositories:
  - ./templates
templates:
  template-with-predefined-component-name:
    source: ./templates/react/my-template
    defaults:
      componentName: Box

You can create this quickly by running scaf customize.