sndicate-js

Command line utility for developing, installing, and generally working with Sndicate front-end modules.

Usage no npm install needed!

<script type="module">
  import sndicateJs from 'https://cdn.skypack.dev/sndicate-js';
</script>

README

Sndicate-commands

This code is under very active development! Don't use it until this message has been removed from the readme!

Commands for developing, installing, and generally working with Sndicate front-end modules

Installation

This tool requires Node >=0.10.30 and grunt-cli (npm install -g grunt-cli for development)

sndicate-dash and Plastic Icicle already come bundled with sndjs as a runtime dependency.

From NPM:

$ npm install -g sndicate-js

Or build from scratch:

$ git clone https://github.com/Sndicate/sndicate-js.git && cd $_
$ npm install
$ grunt build

That's it. The build step will take care of running npm link so you can run the executable.

Usage

Within your own theme

It is recommended that all theme developers include sndicate-js as a dependency in their themes. Including this package gives end users and developers access to the sndjs executable which exposes commands for installing and generally working with third party themes. See the command list below.

Standalone

The sndicate-js binary exposes an sndjs command with the following actions and flags that can be used by developers when working on any front-end Sndicate modules slated for inclusion in sndicate-core. This utility is slated to become a dependency of Plastic Icicle and sndicate-dash so there will be no need to install it when working on those projects.

Commands

All commands must be run within the root of your module or theme.

Packaging modules - sndjs package ...

The package command will prepare a module for production and move it into the correct directory in your Sndicate installation's root.

Arguments and flags:

  • mode (Optional) - The type of module you are packaging. Options are theme and module. Defaults to theme
  • dist (Optional) - The name of the folder containing your built files (as a result of a Grunt or other build task, for example). Defaults to dist
  • installPath (Required) - The path to your Sndicate installation

Examples

# Packaging a theme
sndjs package ../path/to/sndicate-core

# Packaging a module
sndjs package module ../path/to/sndicate-core

The following happens in order when running this command:

  1. Determine the module type (if no type is specified it assumes you are packaging a theme)
  2. The utility reads your package.json file from which it generates a valid manifest.yml file
    • You need to add a _sndManifest object to your package.json file. TODO: Document _sndManifest and link to theme docs
  3. Move the dist folder containing your final built theme to /path/to/sndicate-core/themes/your-theme-name (if type is module, the folder is copied to the corresponding path for the module type)

Generate a module - sndjs generate ...

The generate command creates a project skeleton for themes and generic modules with minimal boilerplate code, default directory structure, and required files. Settings for directory structure and some other settings can be overridden in the _sndManifest object in package.json after creation. TODO: Document module manifests.

Arguments and flags:

  • type (Optional) - The type of module to generate. Defaults to theme
  • name - The name of the module to generate (like the Rails generator or sort of like what Yeoman provides)

When generating a package you will be asked a few questions. Your answers to these will generate a valid package.json file that's compatible with npm with an additional _sndManifest object containing information needed to package your module when you're ready to publish it. Note that this is where you'll be able to override some module defaults. Once installed you'll be asked to run two commands (cd into your new project and run npm install).

Publishing commands

TODO: Write documentation

Contributing

Check out Contributing.md for more on this.

License (MIT)

See License.