Javascript API

If you'd like to use spike programmatically, we have made sure to make this as simple as possible. spike is actually written around it's javascript API, and the CLI sits on top of this as a convenience layer, so you can be sure that we have put a lot of attention into this interface.

Spike's javascript API can be loaded up and installed via the spike-core package.

📘

Code Style

All code examples in this section will use ES6, and run properly only in Node.js v6.0.0 and above. If you are trying to run them using an older node version, you will encounter errors. This project also follows standard js and all examples will adhere to this style.

Class & Constructor

The spike-core module exposes a single class through which all functionality operates. An instance of the class should be created for each project being compiled with spike.

JavaScript

const Spike = require('spike-core')

let project = new Spike({ root: 'path/to/project/root' })

The above shows a minimal instantiation, but the constructor accepts all of the same options accepted by the app.js file, so feel free to pass any of these in. Note that options passed in through the constructor directly will override any values loaded from app.js files if there is a conflict.

Note that each project is an event emitter, and all feedback on what the project is doing will come back through events on the project instance. Currently the following events are supported:

• warning: the project has emitted a warning - not fatal but should be checked out
• error: there was an error and the task will not complete correctly
• info: there is some information about the progress of a task
• done: spike has successfully completed a task (returns some sort of object to be analyzed with javascript)
• success: spike has successfully completed a task (returns a string describing the status)

And these events, which are a little more specific to certain tasks:

• compile: the project has finished compiling one time
• remove: spike has removed a particular path

Creating a New Project

If you want to create a new project from a template, you can use the Spike.new static method. This method utilizes sprout to create a new project template. It accepts an object with the following keys:

root	[required] An absolute path to the root of your project
template	Name of the template you want to use to initialize your project.	base or default template setting
locals	If your template accepts options, you can pass them in here.
emitter	In order to get feedback from the method on how it is progressing through the new template creation progress, pass in an EventEmitter instance here and it will emit info, error, and done events where appropriate.
inquirer	If you want to collect locals from the user via CLI, you can pass in an instance of inquirer.prompt here.

Spike.new

Utilizing Spike.new is fairly straightforward, here's a brief example of how it could be used to collect template locals from the command line using inquirer:

JavaScript

const Spike = require('spike-core')
const inquirer = require('inquirer')
const {EventEmitter} = require('events')
const emitter = new EventEmitter()

emitter.on('info', console.log)
emitter.on('error', console.error)
emitter.on('done', (p) => console.log(`project created at ${p.config.context}`))

Spike.new({
  root: 'path/to/future/project',
  emitter: emitter,
  inquirer: inquirer.prompt.bind(inquirer)
})

project.compile

To compile an instantiated project, you can run project.compile(). This method will synchronously return an instance of webpack's compiler as well as a unique id, which can be used to track events related to this particular compile if necessary. You must be listening for the events you are interested in before calling compile if you want to eliminate the possibility of a race condition.

JavaScript

const Spike = require('spike-core')

const project = new Spike({ root: 'path/to/project/root' })

project.on('info', console.log)
peoject.on('error', console.error)
project.on('compile', console.log)

const {id, compiler} = project.compile()

project.watch

To watch a project, which will initialize a long-running process and multiple compiles, you can use the project.watch function. It returns an id as well as an instance of webpack's watcher. In order to cancel the watcher programmatically, you must use the watcher instance that it returns.

JavaScript

const Spike = require('spike')
const project = new Spike({ root: 'path/to/project' })

project.on('error', console.error)
project.on('warning', console.error)
project.on('compile', console.log)

const {id, watcher} = project.watch()

project.clean

This will remove the output of the current project directory asynchronously.

JavaScript

const Spike = require('spike')
const project = new Spike({ root: 'path/to/project' })

project.on('remove', console.log)

project.clean()

Template Functions

All of spike's template options can also be controlled directly though the JS API. They are all static methods, so you don't need to instantiate the class to use them. Just going to drop usage examples for each one, as they are fairly simple and self-explanitory. More details on how these functions are used can be found in the project templates docs.

Spike.template.add

JavaScript

const EventEmitter = require('events')
const emitter = new EventEmitter()

emitter.on('info', console.log)
emitter.on('error', console.error)
emitter.on('success', console.log)

Spike.template.add({
  name: 'test',
  src: 'https://github.com/test/test',
  emitter: emitter
})

Spike.template.remove

JavaScript

const EventEmitter = require('events')
const emitter = new EventEmitter()

emitter.on('info', console.log)
emitter.on('success', console.log)

Spike.template.remove({ name: 'test' emitter: emitter })

Spike.template.default

JavaScript

const EventEmitter = require('events')
const emitter = new EventEmitter()

emitter.on('info', console.log)
emitter.on('error', console.log)
emitter.on('success', console.log)

Spike.template.default({ name: 'test' emitter: emitter })

This is a sync function and will also return directly if you don't pass an event emitter.

JavaScript

const result = Spike.template.default({ name: 'test' emitter: emitter })
console.log(result)

Spike.template.list

JavaScript

const EventEmitter = require('events')
const emitter = new EventEmitter()

emitter.on('info', console.log)
emitter.on('success', console.log)

Spike.template.list({ emitter: emitter })

This is a sync function and will also return directly if you don't pass an event emitter.

JavaScript

const result = Spike.template.list()
console.log(result)

Spike.template.reset

JavaScript

Spike.template.reset()

This is a sync function with no return value, it will just reset templates and config.

Global Configuration

Spike has a global config file that holds on to an id and the default template settings. You can grab the path to this file through Spike.configPath, and the file's contents with Spike.globalConfig(), which synchronously returns an object containing config values. You can also grab the path where all spike's templates are stored with Spike.tplPath