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 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.
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-preval
Important notes:
- All code run by
preval
is not run in a sandboxed environment - All code must run synchronously.
- All code will be transpiled via
babel-core
directly orbabel-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.
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" };
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']
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'
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
.babelrc
{
"plugins": ["preval"]
}
babel --plugins preval script.js
require('babel-core').transform('code', {
plugins: ['preval'],
})
Use with babel-macros
Once you've configured babel-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.macro
if you'd prefer to type less 😀
- Mastodon saved 40kb
(gzipped) using
babel-plugin-preval
- glamorous-website
uses
preval.macro
to determine Algolia options based onprocess.env.LOCALE
. It also usespreval.macro
to load ansvg
file as a string,base64
encode it, and use it as abackground-url
for an input element.
How is this different from prepack?
prepack
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.
This plugin was inspired by webpack's val-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 webpack
, 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
.
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 twitch.
I was inspired by the val-loader from webpack.
preval.macro
- nicer integration withbabel-macros
I'm not aware of any, if you are please make a pull request and add it here!
Thanks goes to these people (emoji key):
Kent C. Dodds 💻 📖 🚇 |
Matt Phillips 💻 📖 |
Philip Oliver 🐛 |
Sorin Davidoi 🐛 💻 |
---|
This project follows the all-contributors specification. Contributions of any kind welcome!
MIT