babel-plugin-codegen

babel-plugin-codegen 💥

Generate code at build-time

---

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 to glamorous (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.

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.

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

npm install --save-dev babel-plugin-codegen

Usage

This package works in a very similar way to babel-plugin-preval 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:

1. All code run by codegen is not run in a sandboxed environment
2. All code must run synchronously.
3. All code will be transpiled via babel-core directly or babel-register and should follow all of the normal rules for .babelrc resolution (the closest .babelrc to the file being run is the one that's used). This means you can rely on any babel plugins/transforms that you're used to using elsewhere in your codebase.
4. The code that's generated may or may not be transpiled (babel plugin ordering is tricky business). You should generate the code that you wish to ship.

TODO...

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!';

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 = 3

import comment

Before:

import /* codegen */ './assign-one.js'

After (assign-one.js is: module.exports = 'var x = 1'):

var x = 1;

You 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 = 3;

codegen.require

Before:

const x = codegen.require('./es6-identity', 3)

After (es6-identity.js is: export default input => 'var x = ' + JSON.stringify(input) + ';'):

const x = 3;

codegen 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.

Before:

// @codegen
const array = ['apple', 'orange', 'pear']
module.exports = array
  .map(fruit => `export const ${fruit} = '${fruit}';`)
  .join('')

After:

export const apple = 'apple';
export const orange = 'orange';
export const pear = 'pear';

Configure with Babel

Via .babelrc (Recommended)

.babelrc

{
  "plugins": ["codegen"]
}

Via CLI

babel --plugins codegen script.js

Via Node API

require('babel-core').transform('code', {
  plugins: ['codegen'],
})

Use with babel-macros

Once you've configured babel-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";

You could also use codegen.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!

Inspiration

I built this to solve a problem I was experiencing with glamorous. It's heavily based on my work in babel-plugin-preval.

Other Solutions

I'm not aware of any, if you are please make a pull request and add it here!

Contributors

Thanks goes to these people (emoji key):

Kent C. Dodds 💻 📖 🚇 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!

LICENSE

MIT