babel-plugin-preval weekly downloads statistics

babel-plugin-preval

Pre-evaluate code at build-time

[![Build Status][build-badge]][build] [![Code Coverage][coverage-badge]][coverage] [![version][version-badge]][package] [![downloads][downloads-badge]][npmtrends] [![MIT License][license-badge]][license]

[![PRs Welcome][prs-badge]][prs] [![Code of Conduct][coc-badge]][coc] [![Babel Macro][macros-badge]][babel-plugin-macros] [![Examples][examples-badge]][examples]

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:

Or, more interestingly:

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

• Installation • Usage • Template Tag • import comment • preval.require • preval file comment (// @preval) • Exporting a function • Configure with Babel • Via .babelrc (Recommended) • Via CLI • Via Node API • Use with babel-plugin-macros • Examples • Notes • FAQ • How is this different from prepack? • How is this different from webpack loaders? • Inspiration • Related Projects • Other Solutions • Issues • 🐛 Bugs • 💡 Feature Requests • Contributors ✨ • LICENSE

Installation

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

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:

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

preval can also handle _some_ simple dynamic values as well:

Before:

After (assuming ./name-splitter is a function that splits a name into first/last):

import comment

Before:

After (depending on what ./get-list-of-files does, it might be something like):

You can also provide arguments which themselves are prevaled!

Before:

After (assuming ./get-list-of-files accepts an argument limiting how many files are retrieved:

preval.require

Before:

After:

And you can provide _some_ simple dynamic arguments as well:

Before:

After:

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:

After:

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:

Usage of preval:

Generated code:

Configure with Babel

Via .babelrc (Recommended)

.babelrc

Via CLI

Via Node API

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:

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

Examples

• Mastodon saved 40kb (gzipped) using babel-plugin-preval • glamorous-website uses [preval.macro][preval.macro] to determine Algolia options based on process.env.LOCALE. It also uses [preval.macro][preval.macro] to load an svg file as a string, base64 encode it, and use it as a background-url for an input element. • Generate documentation for React components • Serverless with webpack build serverless functions using webpack and Babel for development and production with preval to replace (possible sensible) content in code. • Read files at build time (video)

Notes

If you use babel-plugin-transform-decorators-legacy, there is a conflict because both plugins must be placed at the top

Wrong:

Ok:

FAQ

How is this different from prepack?

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

How is this different from webpack loaders?

This plugin was inspired by webpack's [val-loader][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][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.

If you want to learn more, check webpack documentations about [loaders][webpack-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-loader][val-loader] from webpack.

Related Projects

• [preval.macro][preval.macro] - nicer integration with babel-plugin-macros • define_macro-loader - Integrate preval with C-Like macros, thus, increasing preval use cases.

Other Solutions…

Description from the npm listing.