{"id":26509604,"url":"https://github.com/ember-cli/broccoli-babel-transpiler","last_synced_at":"2025-03-21T01:08:23.647Z","repository":{"id":21755895,"uuid":"25077882","full_name":"ember-cli/broccoli-babel-transpiler","owner":"ember-cli","description":"Broccoli plugin for Babel","archived":false,"fork":false,"pushed_at":"2025-03-19T17:40:20.000Z","size":1963,"stargazers_count":58,"open_issues_count":18,"forks_count":73,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-21T01:08:18.519Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ember-cli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["babel"],"open_collective":"babel","custom":"https://gitcoin.co/grants/2906/babel-compiler-for-next-generation-javascript"}},"created_at":"2014-10-11T12:47:58.000Z","updated_at":"2025-03-20T17:16:44.000Z","dependencies_parsed_at":"2025-03-21T01:08:22.321Z","dependency_job_id":null,"html_url":"https://github.com/ember-cli/broccoli-babel-transpiler","commit_stats":{"total_commits":319,"total_committers":46,"mean_commits":6.934782608695652,"dds":0.6959247648902822,"last_synced_commit":"e287816acd29331be67c22552c7c82a6d83283f0"},"previous_names":["6to5/broccoli-6to5-transpiler","ember-cli-repository-transfers/broccoli-babel-transpiler","ember-cli/broccoli-babel-transpiler"],"tags_count":74,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-cli%2Fbroccoli-babel-transpiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-cli%2Fbroccoli-babel-transpiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-cli%2Fbroccoli-babel-transpiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-cli%2Fbroccoli-babel-transpiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ember-cli","download_url":"https://codeload.github.com/ember-cli/broccoli-babel-transpiler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244717335,"owners_count":20498284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2025-03-21T01:08:22.738Z","updated_at":"2025-03-21T01:08:23.632Z","avatar_url":"https://github.com/ember-cli.png","language":"JavaScript","funding_links":["https://github.com/sponsors/babel","https://opencollective.com/babel","https://gitcoin.co/grants/2906/babel-compiler-for-next-generation-javascript"],"categories":[],"sub_categories":[],"readme":"# broccoli-babel-transpiler\n\n[![Build Status](https://travis-ci.org/babel/broccoli-babel-transpiler.svg?branch=master)](https://travis-ci.org/babel/broccoli-babel-transpiler)\n[![Build status](https://ci.appveyor.com/api/projects/status/a0nbd84m1x4y5fp5?svg=true)](https://ci.appveyor.com/project/embercli/broccoli-babel-transpiler)\n\n\nA [Broccoli](https://github.com/broccolijs/broccoli) plugin that runs [Babel](https://github.com/babel/babel) plugins with caching and parallel capabilities.\n\n## How to install?\n\n```sh\n$ npm install broccoli-babel-transpiler --save-dev\n```\n\n## How to use?\n\nIn your `Brocfile.js`:\n\n```js\nconst babel = require('broccoli-babel-transpiler');\nconst scriptTree = babel(inputTree, babelOptions);\n```\n\nNote that, since Babel 6 (and v6 of this plugin), you need to be specific as to\nwhat your transpilation target is. Running `esTranspiler` with empty options\nwill not transpile anything. You will need:\n\n  * Explicit options, such as `presets`. See available [options](https://babeljs.io/docs/usage/options) at Babel's GitHub repo.\n  * Babel plugins that implement the transforms you require.\n\nFor a quick running example, install this plugin:\n\n```sh\n$ npm install babel-preset-env\n```\n\nAnd then run the transform like this:\n\n```js\nconst babel = require('broccoli-babel-transpiler');\nlet scriptTree = babel(inputTree, {\n  presets: [\n    ['env', {\n      'targets': {\n        'browsers': ['last 2 versions']\n      }\n    }]\n  ]\n});\n```\n\n### Examples\n\nYou'll find three example projects using this plugin in the repository\n[broccoli-babel-examples](https://github.com/givanse/broccoli-babel-examples).\nEach one of them builds on top of the previous example so you can progress from\nbare minimum to ambitious development.\n\n * [es6-fruits](https://github.com/givanse/broccoli-babel-examples/tree/master/es6-fruits) - Execute a single ES6 script.\n * [es6-website](https://github.com/givanse/broccoli-babel-examples/tree/master/es6-website) - Build a simple website.\n * [es6-modules](https://github.com/givanse/broccoli-babel-examples/tree/master/es6-modules) - Handle modules and unit tests.\n\n## About source map\n\nCurrently this plugin only supports inline source map. If you need\nseparate source map feature, you're welcome to submit a pull request.\n\n## Advanced usage\n\n`filterExtensions` is an option to limit (or expand) the set of file extensions\nthat will be transformed.\n\nThe default `filterExtension` is `js`\n\n```js\nconst esTranspiler = require('broccoli-babel-transpiler');\nlet scriptTree = esTranspiler(inputTree, {\n    filterExtensions:['js', 'es6'] // babelize both .js and .es6 files\n});\n```\n\n`targetExtension` is an option to specify the extension of the output files\n\nThe default `targetExtension` is `js`\n\n```js\nconst esTranspiler = require('broccoli-babel-transpiler');\nlet scriptTree = esTranspiler(inputTree, {\n    targetExtension: 'module.js' // create output files with module.js extension\n});\n```\n\n## Plugins\n\nUse of custom plugins works similarly to `babel` itself. You would pass a\n`plugins` array in `options`:\n\n```js\nconst esTranspiler = require('broccoli-babel-transpiler');\nconst applyFeatureFlags = require('babel-plugin-feature-flags');\n\nlet featureFlagPlugin = applyFeatureFlags({\n  import: { module: 'ember-metal/features' },\n  features: {\n    'ember-metal-blah': true\n  }\n});\n\nlet scriptTree = esTranspiler(inputTree, {\n  babel: {\n    plugins: [\n      featureFlagPlugin\n    ]\n  }\n});\n```\n\n### Caching\n\nbroccoli-babel-transpiler uses a persistent cache to enable rebuilds to be\nsignificantly faster (by avoiding transpilation for files that have not\nchanged). However, since a plugin can do many things to affect the transpiled\noutput it must also influence the cache key to ensure transpiled files are\nrebuilt\nif the plugin changes (or the plugins configuration).\n\nIn order to aid plugin developers in this process, broccoli-babel-transpiler\nwill invoke two methods on a plugin so that it can augment the cache key:\n\n* `cacheKey` - This method is used to describe any runtime information that may\n  want to invalidate the cached result of each file transpilation. This is\n  generally only needed when the configuration provided to the plugin is used\n  to modify the AST output by a plugin like `babel-plugin-filter-imports`\n  (module\n  exports to strip from a build), `babel-plugin-feature-flags` (configured\n  features and current status to strip or embed in a final build), or\n  `babel-plugin-htmlbars-inline-precompile` (uses `ember-template-compiler.js`\n  to compile inlined templates).\n* `baseDir` - This method is expected to return the plugins base dir. The\n  provided `baseDir` is used to ensure the cache is invalidated if any of the\n  plugin's files change (including its deps). Each plugin should implement\n  `baseDir` as: `Plugin.prototype.baseDir = function() { return \\_\\_dirname;\n  };`.\n\n## Parallel Transpilation\n\nbroccoli-babel-transpiler can run multiple babel transpiles in parallel using a\npool of workers, to take advantage of multi-core systems. Because these workers\nare separate processes, the plugins and callback functions that are normally\npassed as options to babel must be specified in a serializable form.\nTo enable this parallelization there is an API to tell the worker how to\nconstruct the plugin or callback in its process.\n\nTo ensure a build remains parallel safe, one can set the\n`throwUnlessParallelizable` option to true (defaults to false). This will cause\nan error to be thrown, if parallelization is not possible due to an\nincompatible babel plugin.\n\n```js\nnew Babel(input, { throwUnlessParallelizable: true | false });\n```\n\nAlternatively, an environment variable can be set:\n\n```sh\nTHROW_UNLESS_PARALLELIZABLE=1 node build.js\n```\n\nPlugins are specified as an object with a `_parallelBabel` property:\n\n```js\nlet plugin = {\n  _parallelBabel: {\n    requireFile: '/full/path/to/the/file',\n    useMethod: 'methodName',\n    buildUsing: 'buildFunction',\n    params: { ok: 'this object will be passed to buildFunction()' }\n  }\n};\n```\n\nCallbacks can be specified like plugins, or as functions with a\n`_parallelBabel` property:\n\n```js\nfunction callback() { /* do something */ };\n\ncallback._parallelBabel = {\n  requireFile: '/full/path/to/the/file',\n  useMethod: 'methodName',\n  buildUsing: 'buildFunction',\n  params: { ok: 'this object will be passed to buildFunction()' }\n};\n```\n\n### requireFile (required)\n\nThis property specifies the file to require in the worker process to create the\nplugin or callback. This must be given as an absolute path.\n\n```js\nconst esTranspiler = require('broccoli-babel-transpiler');\n\nlet somePlugin = {\n  _parallelBabel: {\n    requireFile: '/full/path/to/the/file'\n  }\n});\n\nlet scriptTree = esTranspiler(inputTree, {\n  babel: {\n    plugins: [\n      'transform-strict-mode', // plugins that are given as strings will automatically be parallelized\n      somePlugin\n    ]\n  }\n});\n```\n\n### useMethod (optional)\n\nThis property specifies the method to use from the file that is required.\n\nIf you have a plugin defined like this:\n\n```js\n// some_plugin.js\n\nmodule.exports = {\n  pluginFunction(babel) {\n    // do plugin things\n  }\n};\n```\n\nYou can tell broccoli-babel-transpiler to use that function in the worker\nprocesses like so:\n\n```js\nconst esTranspiler = require('broccoli-babel-transpiler');\n\nlet somePlugin = {\n  _parallelBabel: {\n    requireFile: '/path/to/some_plugin',\n    useMethod: 'pluginFunction'\n  }\n});\n\nlet scriptTree = esTranspiler(inputTree, {\n  babel: {\n    plugins: [ somePlugin ]\n  }\n});\n```\n\n### buildUsing and params (optional)\n\nThese properties specify a function to run to build the plugin (or callback),\nand any parameters to pass to that function.\n\nIf the plugin needs to be built dynamically, you can do that like so:\n\n```js\n// some_plugin.js\n\nmodule.exports = {\n  buildPlugin(params) {\n    return doSomethingWith(params.text);\n  }\n};\n```\n\nThis will tell the worker process to require the plugin and call the\n`buildPlugin` function with the `params` object as an argument:\n\n```js\nconst esTranspiler = require('broccoli-babel-transpiler');\n\nlet somePlugin = {\n  _parallelBabel: {\n    requireFile: '/path/to/some_plugin',\n    buildUsing: 'buildPlugin',\n    params: { text: 'some text' }\n  }\n});\n\nlet scriptTree = esTranspiler(inputTree, {\n  babel: {\n    plugins: [ somePlugin ]\n  }\n});\n```\n\nNote: If both `useMethod` and `buildUsing` are specified, `useMethod` takes\nprecedence.\n\n### Number of jobs\n\nThe number of parallel jobs defaults to the number of detected CPUs - 1.\n\nThis can be changed with the `JOBS` environment variable:\n\n```sh\nJOBS=4 ember build\n```\n\nTo disable parallelization:\n\n```sh\nJOBS=1 ember build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fember-cli%2Fbroccoli-babel-transpiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fember-cli%2Fbroccoli-babel-transpiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fember-cli%2Fbroccoli-babel-transpiler/lists"}