babel-plugin-codegen π₯
Generate code at build-time
!Build Statusbuild-badgebuild !Code Coveragecoverage-badgecoverage !versionversion-badgepackage !downloadsdownloads-badgenpmtrends !MIT Licenselicense-badgelicense !All Contributorsall-contributors-badge !PRs Welcomeprs-badgeprs !Code of Conductcoc-badgecoc !Babel Macromacros-badgebabel-plugin-macros
The problem
The applications of this plugin are wide, so it's kinda hard to sum it up, but basically my use case was I needed to add a bunch of named exports toglamorousglamorous (one for every DOM node type) and I didn't want to
maintain the exports in my source file. So someone created a post-build script
to concatenate them to the end of the file. I built this plugin so I could do
that without having an ad-hoc post-build script.Read "Make maintainable workarounds with codegen π₯" for more inspiration
This solution
This plugin allows you to generate code at build-time. Any code that runs synchronously in node can be used to generate a string of code and that string will be inserted in place of where your usage appears.It works by accepting your code string (or module when using the
// @codegen
comment directive) and requiring it as a module. Then it takes whatever the
export was (which should be a string) and converts that string to an AST node
and swaps your usage node with the new AST node.Table of Contents
- Template Tag - import comment - codegen.require - codegen file comment (
// @codegen)
- Via .babelrc (Recommended)
- Via CLI
- Via Node API
- APIs not supported by the macro
- π Bugs
- π‘ Feature RequestsInstallation
This module is distributed via npmnpm which is bundled with nodenode and should be installed as one of your project'sdevDependencies:npm install --save-dev babel-plugin-codegenUsage
This package works in a very similar way tobabel-plugin-prevalpreval
except in this case instead of any value being replaced in the code, you're
actually replacing it with code (giving you a little bit more power in exchange
for potentially being a little more confusing).Important notes:
- All code run by
codegenis not run in a sandboxed environment - All code must run synchronously.
You may like to watch this YouTube video to get an idea of what codegen is and how it can be used.
Template Tag
Before:codegen`
const fs = require('fs')
module.exports = fs.readFileSync(require.resolve('./some-code.js'), 'utf8')
`After (assuming
some-code.js contains the text: var x = 'Hello world!'):var x = 'Hello world!'Here you can see the difference between this plugin and babel-plugin-preval, which would output the content of
some-code.js as a string instead:"var x = 'Hello world!'"codegen can also handle some simple dynamic values as well:Before:
const three = 3
const x = codegen`module.exports = '${three}'`After:
const three = 3
const x = 3import comment
Before:import /* codegen */ './assign-one.js'After (
assign-one.js is: module.exports = 'var x = 1'):var x = 1You can also provide arguments! In this case, the module you import should export a function which accepts those arguments and returns a string.
Before:
import /* codegen(3) */ './assign-identity'After (
assign-identity.js is:
module.exports = input => 'var x = ' + JSON.stringify(input) + ';'):var x = 3codegen.require
Before:codegen.require('./es6-identity', 3)After (
es6-identity.js is:
export default input => 'var x = ' + JSON.stringify(input) + ';'):var x = 3codegen file comment (// @codegen)
Using the codegen file comment will update a whole file to be evaluated down to
an export.Whereas the above usages (assignment/import/require) will only codegen the scope of the assignment or file being imported.
Here is an example of painless
index.js which auto import same depth js files
at compile time.Before:
// @codegen
const fs = require("fs");
const path = require("path");
const regx_JSFiles = /\.(es6|js|es|jsx|mjs|ts)$/;
const name = require("path").basename(__filename);
module.exports = fs.readdirSync(__dirname).reduce((acc, cur) => {
if (name !== cur && regx_JSFiles.test(cur)) {
acc += `export * from './${cur.replace(regx_JSFiles, "")}'\n`;
}
return acc;
}, "");After:
export * from './apple';
export * from './orange';
export * from './pear';Configure with Babel
Via .babelrc (Recommended)
.babelrc{
"plugins": ["codegen"]
}Via CLI
babel --plugins codegen script.jsVia Node API
require('babel-core').transform('code', {
plugins: ['codegen'],
})Use with babel-plugin-macros
Once you've
configured babel-plugin-macros
you can import/require the codegen macro at babel-plugin-codegen/macro. For
example:import codegen from 'babel-plugin-codegen/macro'
codegen`module.exports = ['a', 'b', 'c'].map(l => 'export const ' + l + ' = ' + JSON.stringify(l)).join(';')`
β β β β β β
export const a = "a";
export const b = "b";
export const c = "c";APIs not supported by the macro
You could also use codegen.macrocodegen.macro if you'd prefer to type
less πCaveats
One really important thing to note here is that it doesn't work by simply replacing your code with whatever string you export. Instead it replaces it at the AST level. This means that the resulting code should operate the same, but the format of the code could be entirely different. Most of the time this should not matter, but if it matters to you, please feel free to contribute back if you feel like you could make it work!Examples
practical use case for solving an i18n problem usingcodegen.macroInspiration
I built this to solve a problem I was experiencing with glamorousglamorous. It's heavily based on my work in babel-plugin-prevalpreval.Other Solutions
I'm not aware of any, if you are please make a pull requestprs and add it here!Issues
Looking to contribute? Look for the Good First Issuegood-first-issue label.π Bugs
Please file an issue for bugs, missing documentation, or unexpected behavior.See Bugsbugs
π‘ Feature Requests
Please file an issue to suggest new features. Vote on feature requests by adding a π. This helps maintainers prioritize what to work on.See Feature Requestsrequests
Contributors β¨
Thanks goes to these people (emoji keyemojis):This project follows the all-contributorsall-contributors specification. Contributions of any kind welcome!
