Ember CLI Funnel - File Exclusion

Common errors

• Error: Cannot find module 'ember-cli-funnel'

  cause Attempting to `require` or `import` `ember-cli-funnel` directly into an application JavaScript file or even `ember-cli-build.js`.
  fix `ember-cli-funnel` is an Ember CLI addon that extends the `EmberApp` build options. It is not directly imported into JavaScript files. Ensure it is listed in your `package.json` and that `ember install ember-cli-funnel` has been run.

• My files aren't being excluded in development! (or other non-production environments)

  cause The `funnel.enabled` option defaults to `true` only in the production environment to optimize development build times.
  fix To apply file exclusions in development or other environments, you must explicitly set `enabled: true` in your `ember-cli-build.js` configuration: `funnel: { enabled: true, exclude: [...] }`.

• Build fails or includes unexpected files after upgrading Ember CLI or Node.js versions.

  cause The package, being pre-1.0 and supporting older Node.js engines (`6.* || 8.* || >= 10.*`), may have underlying Broccoli dependencies or integration mechanisms with `EmberApp` that are not fully compatible with newer Ember CLI or Node.js versions without updates.
  fix Check the `ember-cli-funnel` GitHub issues and pull requests for any known compatibility issues or updates required for your specific Ember CLI and Node.js versions. Consider using `ember try:each` to test against multiple Ember versions to identify the breaking point.

Warnings

• gotcha The `enabled` option for `funnel` defaults to `true` only in `production` environments. If you intend to use file exclusion in `development`, `test`, or other non-production environments, you must explicitly set `enabled: true` in your `ember-cli-build.js` configuration.
  Fix: Explicitly set `enabled: true` within the `funnel` configuration object in `ember-cli-build.js`: `funnel: { enabled: true, exclude: [...] }`.
• breaking As a pre-1.0 release (version 0.6.1), the API and configuration options for `ember-cli-funnel` may be subject to backward-incompatible changes in future minor or patch releases, although no specific breaking changes are documented in the provided README. Developers should be cautious when upgrading within the 0.x range.
  Fix: Refer to the project's GitHub releases or changelog for specific breaking changes if upgrading within the 0.x range. It is advisable to pin exact versions (e.g., `"ember-cli-funnel": "0.6.1"`) for stability to avoid unexpected breaking changes.
• gotcha Incorrectly defined glob patterns in the `exclude` array can lead to unexpected files being included or excluded, potentially causing runtime errors, build failures, or bloating the build output. Paths are typically relative to the project root or the `addon-tree-output` for files originating from other addons.
  Fix: Thoroughly test exclusion patterns by running `ember serve` and inspecting the `dist/` directory. Use tools like `glob-explorer` or `tree` to visualize path matching. Pay close attention to the distinction between application-specific file paths and those residing within the `addon-tree-output` directory.

Install

• npm install ember-cli-funnel npm
• yarn add ember-cli-funnel yarn
• pnpm add ember-cli-funnel pnpm

Imports

• EmberApp
  wrong:

  import EmberApp from 'ember-cli/lib/broccoli/ember-app';

  correct:

  const EmberApp = require('ember-cli/lib/broccoli/ember-app');

  `ember-cli-build.js` files, where `ember-cli-funnel` is configured, traditionally use CommonJS `require` syntax. The addon's functionality is activated by passing a `funnel` option to the `EmberApp` constructor.
• funnel (configuration option)
  wrong:

  import funnel from 'ember-cli-funnel';

  correct:

  let app = new EmberApp(defaults, { funnel: { exclude: ['some/path/**/*'] } });

  The `funnel` property is a specific configuration object understood by the `ember-cli-funnel` addon when present in the `EmberApp` options. It is not a standalone module to be imported directly into your JavaScript files.
• getRepoInfo (from git-repo-info)
  wrong:

  import getRepoInfo from 'git-repo-info';

  correct:

  let getRepoInfo = require('git-repo-info');

  For advanced dynamic exclusions based on Git repository information, `git-repo-info` is an external development dependency that is `require`d in `ember-cli-build.js`.

Quickstart

This quickstart demonstrates how to configure `ember-cli-funnel` within `ember-cli-build.js` to exclude specific application routes and addon styles from the final build output based on glob patterns and environment.

// ember-cli-build.js
'use strict';

const EmberApp = require('ember-cli/lib/broccoli/ember-app');
const path = require('path');

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    // Configure ember-cli-funnel to exclude specific files from the build
    funnel: {
      // Array of glob patterns for files/directories to exclude
      exclude: [
        // Exclude an entire route folder named 'style-guide' from the app's output
        `${defaults.project.pkg.name}/routes/style-guide/**/*`,
        // Exclude SCSS files from a specific addon's tree output
        'addon-tree-output/some-addon/styles/**/*.scss'
      ],
      // The 'enabled' option defaults to true only in production. 
      // Explicitly enable it for other environments if needed.
      enabled: process.env.EMBER_ENV === 'development' || process.env.EMBER_ENV === 'production'
    }
  });

  // Return the final Broccoli tree for the build process
  return app.toTree();
};