Not Preposterously Macho
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    @glimmer/application-pipelinepublic

    glimmer-application-pipeline

    npm version Build Status

    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.

    install

    npm i @glimmer/application-pipeline

    Downloadsweekly downloads

    149

    version

    0.11.1

    license

    MIT

    repository

    githubgithub

    last publish

    collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar