babel-plugin-preval

Pre-evaluate code at build-time

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
babel-plugin-preval
1,347105.1.02 years ago7 years agoMinified + gzip package size for babel-plugin-preval in KB

Readme

babel-plugin-preval

Pre-evaluate code at build-time


!Build Statusbuild-badgebuild !Code Coveragecoverage-badgecoverage !versionversion-badgepackage !downloadsdownloads-badgenpmtrends !MIT Licenselicense-badgelicense
All Contributors !PRs Welcomeprs-badgeprs !Code of Conductcoc-badgecoc !Babel Macromacros-badgebabel-plugin-macros !Examplesexamples-badgeexamples

The problem

You need to do some dynamic stuff, but don't want to do it at runtime. Or maybe you want to do stuff like read the filesystem to get a list of files and you can't do that in the browser.

This solution

This allows you to specify some code that runs in Node and whatever you module.exports in there will be swapped. For example:
const x = preval`module.exports = 1`

//      ↓ ↓ ↓ ↓ ↓ ↓

const x = 1

Or, more interestingly:
const x = preval`
  const fs = require('fs')
  const val = fs.readFileSync(__dirname + '/fixture1.md', 'utf8')
  module.exports = {
    val,
    getSplit: function(splitDelimiter) {
      return x.val.split(splitDelimiter)
    }
  }
`

//      ↓ ↓ ↓ ↓ ↓ ↓

const x = {
  val: '# fixture\n\nThis is some file thing...\n',
  getSplit: function getSplit(splitDelimiter) {
    return x.val.split(splitDelimiter)
  },
}

There's also preval.require('./something') and import x from /* preval */ './something' (which can both take some arguments) or add // @preval comment at the top of a file.
See more below.

Table of Contents


- Template Tag - import comment - preval.require - preval file comment (// @preval) - Via .babelrc (Recommended) - Via CLI - Via Node API - How is this different from prepack? - How is this different from webpack loaders? - 🐛 Bugs - 💡 Feature Requests

Installation

This module is distributed via npmnpm which is bundled with nodenode and should be installed as one of your project's devDependencies:
npm install --save-dev babel-plugin-preval

Usage

Important notes:
  1. All code run by preval is not run in a sandboxed environment
  2. All code must run synchronously.
  3. Code that is run by preval is not transpiled so it must run natively in the
version of node you're running. (cannot use es modules).
You may like to watch this YouTube video to get an idea of what preval is and how it can be used.

Template Tag

Before:
const greeting = preval`
  const fs = require('fs')
  module.exports = fs.readFileSync(require.resolve('./greeting.txt'), 'utf8')
`

After (assuming greeting.txt contains the text: "Hello world!"):
const greeting = 'Hello world!'

preval can also handle some simple dynamic values as well:
Before:
const name = 'Bob Hope'
const person = preval`
  const [first, last] = require('./name-splitter')(${name})
  module.exports = {first, last}
`

After (assuming ./name-splitter is a function that splits a name into first/last):
const name = 'Bob Hope'
const person = {first: 'Bob', last: 'Hope'}

import comment

Before:
import fileList from /* preval */ './get-list-of-files'

After (depending on what ./get-list-of-files does, it might be something like):
const fileList = ['file1.md', 'file2.md', 'file3.md', 'file4.md']

You can also provide arguments which themselves are prevaled!
Before:
import fileList from /* preval(3) */ './get-list-of-files'

After (assuming ./get-list-of-files accepts an argument limiting how many files are retrieved:
const fileList = ['file1.md', 'file2.md', 'file3.md']

preval.require

Before:
const fileLastModifiedDate = preval.require('./get-last-modified-date')

After:
const fileLastModifiedDate = '2017-07-05'

And you can provide some simple dynamic arguments as well:
Before:
const fileLastModifiedDate = preval.require(
  './get-last-modified-date',
  '../../some-other-file.js',
)

After:
const fileLastModifiedDate = '2017-07-04'

preval file comment (// @preval)

Using the preval file comment will update a whole file to be evaluated down to an export.
Whereas the above usages (assignment/import/require) will only preval the scope of the assignment or file being imported.
Before:
// @preval

const id = require('./path/identity')
const one = require('./path/one')

const compose = (...fns) => fns.reduce((f, g) => a => f(g(a)))
const double = a => a * 2
const square = a => a * a

module.exports = compose(square, id, double)(one)

After:
module.exports = 4

Exporting a function

If you export a function from a module that you're prevaling (whether using preval.require or the import comment), then that function will be called and whatever is returned will be the prevaled value.
It's important to know this if you want to have the prevaled value itself be a function:
Example:
// example-module.js
const fn = message => `The message is: ${message}`
module.exports = () => fn

Usage of preval:
const theFn = preval.require('./example-module.js')

Generated code:
const theFn = message => `The message is: ${message}`

Configure with Babel

Via .babelrc (Recommended)

.babelrc
{
  "plugins": ["preval"]
}

Via CLI

babel --plugins preval script.js

Via Node API

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

Use with babel-plugin-macros

Once you've configured babel-plugin-macros you can import/require the preval macro at babel-plugin-preval/macro. For example:
import preval from 'babel-plugin-preval/macro'

const one = preval`module.exports = 1 + 2 - 1 - 1`

You could also use preval.macropreval.macro if you'd prefer to type less 😀

Examples

(gzipped) using babel-plugin-preval uses preval.macropreval.macro to determine Algolia options based on process.env.LOCALE. It also uses preval.macropreval.macro to load an svg file as a string, base64 encode it, and use it as a background-url for an input element. build serverless functions using webpack and Babel for development and production with preval to replace (possible sensible) content in code.

Notes

If you use babel-plugin-transform-decorators-legacy, there is a conflict because both plugins must be placed at the top
Wrong:
{
  "plugins": ["preval", "transform-decorators-legacy"]
}

Ok:
{
  "plugins": ["preval", ["transform-decorators-legacy"]]
}

FAQ

How is this different from prepack?

prepackprepack is intended to be run on your final bundle after you've run your webpack/etc magic on it. It does a TON of stuff, but the idea is that your code should work with or without prepack.
babel-plugin-preval is intended to let you write code that would not work otherwise. Doing things like reading something from the file system are not possible in the browser (or with prepack), but preval enables you to do this.

How is this different from webpack loaders?

This plugin was inspired by webpack's val-loaderval-loader. The benefit of using this over that loader (or any other loader) is that it integrates with your existing babel pipeline. This is especially useful for the server where you're probably not bundling your code with webpackwebpack, but you may be using babel. (If you're not using either, configuring babel for this would be easier than configuring webpack for val-loader).
In addition, you can implement pretty much any webpack loader using babel-plugin-preval.
If you want to learn more, check webpack documentations about loaderswebpack-loaders.

Inspiration

I needed something like this for the glamorous website. I live-streamed developing the whole thing. If you're interested you can find the recording on my youtube channel (note, screen only recording, no audio).
I was inspired by the val-loaderval-loader from webpack.

Related Projects

Integrate preval with C-Like macros, thus, increasing preval use cases.

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 Bugs
bugs

💡 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):
<td align="center"><a href="https://kentcdodds.com"><img src="https://avatars.githubusercontent.com/u/1500684?v=3?s=100" width="100px;" alt=""/><br /><sub><b>Kent C. Dodds</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=kentcdodds" title="Code">💻</a> <a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=kentcdodds" title="Documentation">📖</a> <a href="#infra-kentcdodds" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=kentcdodds" title="Tests">⚠️</a></td>
<td align="center"><a href="http://mattphillips.io"><img src="https://avatars3.githubusercontent.com/u/5610087?v=3?s=100" width="100px;" alt=""/><br /><sub><b>Matt Phillips</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=mattphillips" title="Code">💻</a> <a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=mattphillips" title="Documentation">📖</a> <a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=mattphillips" title="Tests">⚠️</a></td>
<td align="center"><a href="https://twitter.com/philipodev"><img src="https://avatars1.githubusercontent.com/u/28024000?v=3?s=100" width="100px;" alt=""/><br /><sub><b>Philip Oliver</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/issues?q=author%3Aphilipodev" title="Bug reports">🐛</a></td>
<td align="center"><a href="https://toot.cafe/@sorin"><img src="https://avatars2.githubusercontent.com/u/2109702?v=3?s=100" width="100px;" alt=""/><br /><sub><b>Sorin Davidoi</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/issues?q=author%3Asorin-davidoi" title="Bug reports">🐛</a> <a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=sorin-davidoi" title="Code">💻</a> <a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=sorin-davidoi" title="Tests">⚠️</a></td>
<td align="center"><a href="https://github.com/infiniteluke"><img src="https://avatars4.githubusercontent.com/u/1127238?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Luke Herrington</b></sub></a><br /><a href="#example-infiniteluke" title="Examples">💡</a></td>
<td align="center"><a href="http://instagram.com/luftywiranda13"><img src="https://avatars4.githubusercontent.com/u/22868432?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Lufty Wiranda</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=luftywiranda13" title="Code">💻</a></td>
<td align="center"><a href="http://obartra.github.io"><img src="https://avatars0.githubusercontent.com/u/3877773?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Oscar</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=obartra" title="Code">💻</a> <a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=obartra" title="Tests">⚠️</a></td>
<td align="center"><a href="https://github.com/pro-nasa"><img src="https://avatars1.githubusercontent.com/u/14310216?v=4?s=100" width="100px;" alt=""/><br /><sub><b>pro-nasa</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=pro-nasa" title="Documentation">📖</a></td>
<td align="center"><a href="http://bekrin.me"><img src="https://avatars0.githubusercontent.com/u/9248479?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Sergey Bekrin</b></sub></a><br /></td>
<td align="center"><a href="https://maurobringolf.ch"><img src="https://avatars0.githubusercontent.com/u/18613301?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Mauro Bringolf</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=maurobringolf" title="Code">💻</a> <a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=maurobringolf" title="Tests">⚠️</a></td>
<td align="center"><a href="https://joelim.me"><img src="https://avatars1.githubusercontent.com/u/10875678?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Joe Lim</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=xjlim" title="Code">💻</a></td>
<td align="center"><a href="https://github.com/marzelin"><img src="https://avatars3.githubusercontent.com/u/13483453?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Marcin Zielinski</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=marzelin" title="Code">💻</a></td>
<td align="center"><a href="http://www.tommyleunen.com"><img src="https://avatars3.githubusercontent.com/u/1972567?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Tommy</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=tleunen" title="Code">💻</a></td>
<td align="center"><a href="https://github.com/PlayMa256"><img src="https://avatars0.githubusercontent.com/u/831308?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Matheus Gonçalves da Silva</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=PlayMa256" title="Documentation">📖</a></td>
<td align="center"><a href="https://stackshare.io/jdorfman/decisions"><img src="https://avatars1.githubusercontent.com/u/398230?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Justin Dorfman</b></sub></a><br /><a href="#fundingFinding-jdorfman" title="Funding Finding">🔍</a></td>
<td align="center"><a href="https://github.com/AndrewRot"><img src="https://avatars2.githubusercontent.com/u/12818861?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Andrew Rottier</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=AndrewRot" title="Documentation">📖</a></td>
<td align="center"><a href="https://michaeldeboey.be"><img src="https://avatars3.githubusercontent.com/u/6643991?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Michaël De Boey</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=MichaelDeBoey" title="Code">💻</a></td>
<td align="center"><a href="https://github.com/nobrayner"><img src="https://avatars.githubusercontent.com/u/40751395?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Braydon Hall</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=nobrayner" title="Code">💻</a></td>
<td align="center"><a href="https://dev.to/jacobmgevans"><img src="https://avatars.githubusercontent.com/u/27247160?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jacob M-G Evans</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=JacobMGEvans" title="Code">💻</a></td>
<td align="center"><a href="http://juhanajauhiainen.com"><img src="https://avatars.githubusercontent.com/u/544386?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Juhana Jauhiainen</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=juhanakristian" title="Code">💻</a></td>
<td align="center"><a href="http://peter.hozak.info/"><img src="https://avatars.githubusercontent.com/u/1087670?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Peter Hozák</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=Aprillion" title="Code">💻</a></td>
<td align="center"><a href="https://github.com/mpeyper"><img src="https://avatars.githubusercontent.com/u/23029903?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Michael Peyper</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=mpeyper" title="Code">💻</a></td>
<td align="center"><a href="https://hipreme.itch.io/"><img src="https://avatars.githubusercontent.com/u/10136262?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Marcelo Silva Nascimento Mancini</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=MrcSnm" title="Documentation">📖</a> <a href="#plugin-MrcSnm" title="Plugin/utility libraries">🔌</a></td>
<td align="center"><a href="https://github.com/NMinhNguyen"><img src="https://avatars.githubusercontent.com/u/2852660?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Minh Nguyen</b></sub></a><br /><a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=NMinhNguyen" title="Code">💻</a> <a href="https://github.com/kentcdodds/babel-plugin-preval/commits?author=NMinhNguyen" title="Tests">⚠️</a> <a href="#infra-NMinhNguyen" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>



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

LICENSE

MIT