Integration

You can install Substance via npm and use it with a build tool of your choice.

npm install substance

Let's assume the following project structure.

app - application setup (html, css, js)
lib - reusable library code of your editor
node_modules - dependencies such as substance and font-awesome

Bundling

Now we want to create a distribution (bundle), that combines all those source files into dist folder that can be hosted on a webserver.

dist/index.html - HTML page
dist/app.css - bundled CSS
dist/app.js - bundled Javascript code
dist/substance/*
dist/font-awesome/*

Your index.html file should look like this:

<script type="text/javascript" src="./substance/substance.js"/></script>
<script type="text/javascript" src="./app.js"></script>
<link rel="stylesheet" type="text/css" href="./app.css"/>

Substance Bundler

Substance Bundler is our own build tool, which combines chokidar for file watching, rollup for bundling Javascript, postcss for CSS, and coming with a concept of tasks as you know it from gulp.

First you need to install substance-bundler:

npm install --save-dev substance-bundler

Then write a build script make.js that does the actual work:

var b = require('substance-bundler')

b.task('clean', function() {
  b.rm('./dist')
})

b.task('assets', function() {
  b.copy('node_modules/substance/dist', './dist/substance')
  b.copy('node_modules/font-awesome', './dist/font-awesome')
})

b.task('build', ['clean', 'assets'], function() {
  b.copy('app/index.html', './dist/index.html')
  b.css('app/app.css', './dist/app.css')
  b.js('app/app.js', {
    target: {
      dest: './dist/app.js',
      format: 'umd',
      moduleName: 'app'
    },
    external: ['substance']
  })
})

b.task('default', ['build'])

To create your bundle you run

node make

If you want to look at a complete project setup, just clone and run SimpleWriter.

Browserify and Babel

If you want to build your project with browserify you can do this

First you would install browserify:

npm install -g browserify

They you need to install babelify

npm install babel-preset-es2015 babelify

To bundle dist/app.js you run:

browserify app/app.js -t babelify -o dist/app.js

Rollup and Bublé

You can use rollup together with some plugins to bundle Javascript.

First install rollup:

npm install -g rollup

Then install bublé:

npm install rollup-plugin-buble

Create a rollup.config.js which looks like

import buble from 'rollup-plugin-buble'

export default {
  entry: 'src/app.js',
  plugins: [
    buble()
  ],
  // This tells rollup to consider substance as external dependency
  external: [ 'substance' ],
  format: 'umd',
  moduleName: 'app'
}

To build dist/app.js you run

rollup -c -o dist/app.js

If you want to create a single file bundle, i.e. with Substance code included, you need the following additional plugins

npm install rollup-plugin-node-resolve rollup-plugin-commonjs

And your rollup.config.js looks like:

import resolve from 'rollup-plugin-node-resolve'
import commonjs from 'rollup-plugin-commonjs'
import buble from 'rollup-plugin-buble'

export default {
  entry: 'src/app.js',
  plugins: [
    resolve({
      // consider the browser field in `package.json`
      browser: true,
      // use es6 entry points
      jsnext: true
    }),
    commonjs({
      // lodash is used as commonjs module
      include: [ '/**/lodash-es/**' ]
    }),
    buble()
  ],
  format: 'umd',
  moduleName: 'app'
}

Note: bundling substance into your app.js will slow down your builds a bit.

Other tools

You are free to use other build tools, such as Webpack or Gulp. Please consult the websites of those projects for usage documentation.

Substance comes with a distribution folder dist with following content:

  • substance.js: a UMD bundle for the browser transpiled to ES5. Include it in your webpage and it will register Substance API under window.substance.
  • substance.js.map: source maps for substance.js
  • substance.css: A bundled CSS file indcluding styles for all core packages. It has been transpiled to CSS 2.1, i.e. with variables replaced.
  • substance.css.map: source maps for substance.css
  • subsatnce.next.css: same as substance.css but using modern CSS features, such as CSS variables.
  • substance.css.next.map: source maps for substance.next.css
  • substance-pagestyle.css: pagestyles that we use in our Substance apps.
  • substance-reset.css: CSS that clears default styles.