babel-plugin-preval weekly downloads statistics

<div align="center"> <h1>babel-plugin-preval</h1> <p>Pre-evaluate code at build-time</p> </div>

---

<!-- prettier-ignore-start -->

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

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

<!-- ALL-CONTRIBUTORS-BADGE:END -->

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

<!-- prettier-ignore-end -->

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

<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

• 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

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

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:

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')…