glimmer-application-pipeline

Installation

Add this package to your project with Yarn:

yarn add @glimmer/application-pipeline

Or alternatively with npm:

npm install --save-dev @glimmer/application-pipeline

Usage

This package exports a GlimmerApp class. Using this class enables you to run your application code and assets through a broccoli pipeline, and calling toTree() will return a broccoli node with the processed files:

const { GlimmerApp } = require('@glimmer/application-pipeline');

module.exports = function(defaults) {
  var app = new GlimmerApp(defaults, {
    // Add options here
  });

  return app.toTree();
};

Importing CommonJS modules

The application pipeline only supports ES modules out of the box, but consumers can opt-in to using CommonJS modules themselves. Here is an example of what this looks like:

// ember-cli-build.js
const GlimmerApp = require('@glimmer/application-pipeline').GlimmerApp;
const resolve = require('rollup-plugin-node-resolve');
const commonjs = require('rollup-plugin-commonjs');

module.exports = function(defaults) {
  let app = new GlimmerApp(defaults, {
    rollup: {
      plugins: [
        resolve({ jsnext: true, module: true, main: true }),
        commonjs()
      ]
    }
  });

  return app.toTree();
};

Note that Rollup must be configured when an NPM module rely on global variables. For example, if crypto is being used by one of the modules that is imported into the the app, the additional options to the above for the Rollup config is the following:

rollup: {
  // ...
  external: ['crypto'],
  globals: {
    crypto: 'crypto'
  }
}

Styles and SASS

When an application is generated with ember-cli's blueprint - ember new my-app -b @glimmer/blueprint, it installs ember-cli addon ember-cli-sass which also is used in EmberJS applications. So you can tune it via options for GlimmerApp in the same way as in EmberApp (see details).

One of common requirements is to support imports (@import) from node_modules. For example, we need to import 3rd-party SASS overriding its variable (that's because we can't just use compiled css).

$mdc-theme-accent: #00e871;

@import "../../../node_modules/material-components-web/material-components-web.scss";

By default we'll get an error on building:

Build failed.
The Broccoli Plugin: [BroccoliMergeTrees] failed with:
Error: File to import not found or unreadable: ../../../node_modules/material-components-web/material-components-web.scss.

To fix it we need to tell SASS compiler to look up in node_modules folder:

module.exports = function(defaults) {
  let app = new GlimmerApp(defaults, {
    sassOptions: {
      includePaths: [
        'node_modules'
      ]
    }
});

Customizing production and debug builds

This enables any dependencies that are being built to do the following:

import { DEBUG } from '@glimmer/env';

if (DEBUG) {
  // do things that are supposed to be done in debug builds only
}

A good example of this, is to only install "mandatory setters" for @tracked when running in debug builds. In production we do not want to Object.defineProperty(instance, propertyName, ...) for every property that is used in a template, but we do want this in debug builds so that we can provide nice helpful messaging to the user about what they have potentially done wrong.

This PR also enables automatic warn / assert stripping via:

import { assert } from '@glimmer/debug';

assert(somePredicateGoesHere, 'helpful message when the predicate is not true');

In debug build this is transpiled to something like:

somePredicateGoesHere && console.assert(somePredicateGoesHere, 'helpful message when the predicate is not true');

But in production builds, the entire statement is removed.

Enabling use of async-await in components

First, install regenerator-runtime in your app:

yarn add --dev regenerator-runtime

Then import regenerator-runtime/runtime at the top of src/index.ts:

// src/index.ts
import 'regenerator-runtime/runtime';

Development

For the development of this project, Yarn is preferred over npm. However, any Yarn command can be replaced by the npm equivalent. See Migration from npm in the Yarn documentation for a list of the equivalent commands.

Clone repository locally: git clone https://github.com/glimmerjs/glimmer-application-pipeline.git
Install dependencies: yarn, or yarn install
Open project in your editor of choice and make your changes
Run tests: yarn run test

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/glimmerjs/glimmer-application-pipeline.

Acknowledgements

Thanks to Monegraph for funding the initial development of this library.

License

MIT License.