Sneed

Sneed is a simple scaffolding cli tool for developers, to generate source files based on templates they define and can keep in source control in their project.

• Getting started
• Configuring scaffolding
• Configuring editing
• Variables
• Templating engine
• Path templating
• Helpers - Case transformation
• Helpers - Paths
• Helpers - Lodash
• Examples
• Changelog

Getting started

Install

Install sneed globally

$ npm install -g sneed

or locally & invoke by npm scripts

Initialize environment

Sneed's init command will generate required config & template folder for you

$ sneed init

Define commands

Open created .sneedrc.js in editor & create scaffolding/editing commands as you wish.

See configuration section below

Run scaffolding

Once sneed is configured, you can execute your commands that will generate files based on your definition

$ sneed <your-command> --var1 Value1 --var2 Value2 ...

Configuring scaffolding

Scaffolding is primary feature of Sneed that allows you to generate source code files based on your templates to your desired destination. Sneed allows configuration as .sneedrc, .sneedrc.json, .sneedrc.js, .sneedrc.yaml

Example .sneedrc.js

module.exports = {
  templateFolder: 'templates',
  commands: {
    // name of command (used in cli)
    ScaffoldHelloWorldFile: {
      scaffolds: [
        {
          // your template in "templates" folder
          template: 'hello-world.ejs',
          // destination file path
          target: 'src/hello-world.js'
        }
      ],
      // not important for scaffolding
      edits: [],
      variables: {
        // cli '--greet <value>' argument will passed into template
        greet: {}
      }
    }
  }
}

templates/hello-world.ejs

console.log('<%= greet %>')

Now you can execute scaffolding your command ScaffoldHelloWorldFile to generate src/hello-world.js file

$ sneed ScaffoldHelloWorldFile --greet "Hello world"

which will generate

src/hello-world.js

console.log('Hello world')

For more advanced examples check examples // TODO

Configuring editing

File editing is secondary feature of Sneed and can be used to automatically modify existing source files to insert custom content.

This feature is useful for example if you want Sneed to automatically inject import statements of your newly generated components.

Lets have following: .sneedrc.js

module.exports = {
  templateFolder: 'templates',
  commands: {
    ScaffoldComponentAndRegister: {
      scaffolds: [],
      edits: [
        {
          target: 'src/register-components.js',
          mark: '// SNEED INSERT HERE',
          template: 'register-component.ejs',
          editType: 'insertAfter'
        }
      ],
      variables: {
        name: {}
      }
    }
  }
}

This will be rendered after our "mark"

templates/register-component.ejs

register.component(require('./<%= name %>'))

This is actual source file that we edit

src/register-components.js

register.component(require('./digging'))
register.component(require('./sewing'))
// SNEED INSERT HERE
register.component(require('./brewing'))

Now we execute

$ sneed ScaffoldComponentAndRegister --name building

and Sneed will insert rendered code block right after "// SNEED INSERT HERE" marking resulting in

register.component(require('./digging'))
register.component(require('./sewing'))
// SNEED INSERT HERE
register.component(require('./building'))
register.component(require('./brewing'))

Note that you need to place spaces & newlines into your template manually to correctly insert stuff

Variables

Sneed provides a way how to pass custom data (e.g. component names, switches...) into rendering engine. This way you can customize how your template behaves.

Variables without "default" option are mandatory, and must be specified as CLI option.

Example .sneedrc.js

module.exports = {
  templateFolder: 'templates',
  commands: {
    VariableTest: {
      scaffolds: [
        {
          template: 'vars.ejs',
          target: 'src/vars.txt'
        }
      ],
      edits: [],
      variables: {
        name: {},
        surname: {},
        greet: { default: false }
      }
    }
  }
}

templates/vars.ejs

<% if (greet == 'true') { %>
Greetings fellow citizen,
<% } %>
you have new message <%= name %> <%= surname %>!

Executing comman without --greet switch

$ sneed VariableTest --name John --surname Wick

generates

you have new message John Wick!

Executing comman with --greet switch

$ sneed VariableTest --name John --surname Wick --greet

generates

Greetings fellow citizen,

you have new message John Wick!

Templating engine

Sneed uses EJS templating engine with all its features.

It's recommended to use <%- value %> tags for rendering custom values, as it doesn't escape html chars which might be in your values and would likely result in invalid source code.

<%- %> render unescaped value (<>hello<>):

<%- '<>hello<>' %>

<%= %> render escaped value (<>hello<>):

<%= '<>hello<>' %>

<% %> are used for control flow statements:

<% if (value === 'hello') { %> Hello there <% } %>

<%- include(templateFile, variables) %> for including other templates

<%- include('ClassTemplate', { class: 'Chuck' }) %>

(including is relative to configs "templatesFolder")

Check EJS docs for more!

Path templating

Sneed also templates your paths in config! Temlatable config options are template, target and mark

Example .sneedrc.js

module.exports = {
  templateFolder: 'templates',
  commands: {
    TemplatedPath: {
      scaffolds: [
        {
          template: 'example-template.ejs',
          target: '<%= folder %>/example.js'
        }
      ],
      edits: [],
      variables: {
        folder: {}
      }
    }
  }
}

Allows you to choose denstination path by "--folder" variable

Helpers - Case transformation

Sneed provides set of function from package change-case that can be accessed in templates under casing property. With these functions you can easily reuse identifier names in different casing conventions across your template.

Available functions are: camelCase, capitalCase, constantCase, dotCase, headerCase, noCase, paramCase, pascalCase, pathCase, sentenceCase, snakeCase

see change-case for more

Example template.ejs

class <%= casing.pascalCase(name) %> { }
var <%= casing.camelCase(name) %> = 42

Passing --name hello-world will render

class HelloWorld {}
var helloWorld = 42

Helpers - Paths

Sneed provides path helper function that can be accessed in templates under path property. The functions are from native path package.

Example template.ejs

<%= path.basename('/foo/bar/index.html') %>

will render

index.html

Helpers - Lodash

Sneed provides utility swiss knife package Lodash accessible under property "_" which contains plethora of function for collection and object manipulation, transformation etc...

Examples

• Hello world
• Variables
• Class properties
• Edit root reducer
• React components
• C# Service with Interface

Changelog

0.0.7 (28.08.2021)

Version bump of dependencies