babel-plugin-static-fs

A babel plugin to statically inline Node fs calls. This is useful for building "universal" JavaScript (code that targets the browser and server) and bundler-agnostic modules.

It also can be used as a replacement for brfs in some cases – adding source maps, cleaner output code, ES2015 import support, and more robust handling of unusual syntax.

For example, say you have the following ES2015 source:

import { readFileSync } from 'fs';
import { join } from 'path';
const src = readFileSync(join(__dirname, 'hello.txt'), 'utf8');

And hello.txt is a text file containing the string "Hello, World!".

After transformation, it will look like this:

import { join } from 'path';
const src = 'Hello, World!';

Your ES5 (npm) distribution code is now usable in Node, Browserify, Webpack, JSPM, and everything in between.

Features

Currently supports CommonJS require() statements and common flavours of ES2015 import (no wild cards).

The following fs functions are supported:

• fs.readFileSync(filepath, [enc])
• fs.readdirSync(filepath)

The following path functions will be evaluated statically when they are found inside the arguments of the above calls:

• path.join()
• path.resolve()

You can also use require.resolve() like so:

const fs = require('fs');
const str = fs.readFileSync(require.resolve('./hello.txt'), 'utf8');
console.log(str);

By default, this plugin will gracefully skip expressions that can't be statically evaluated at build time.

Install

npm install babel-plugin-static-fs --save-dev

After installing, you will need to add it to your .babelrc as a new plugin, or set it up as an option to babelify or Webpack's babel-loader.

For example, in browserify:

browserify src/index.js -t [ babelify --plugins static-fs ]

Usage

See babel docs for more info on using plugins.

You can specify an onFile function to the plugin to receive new dependencies.

var staticFs = require('babel-plugin-static-fs');
var babel = require('babel-core');

var result = babel.transform(input, {
  plugins: [
    [ staticFs, {
      target: 'browser', // defaults to node
      dynamic: false, // defaults to true
      onFile: onFile // callback that receives new file dependencies
    } ]
  ],
  filename: filename
});

function onFile (file) {
  console.log('Discovered new dependency:', file);
}

You can specify the { target } field as either 'node' or 'browser', this will only affect transformed require.resolve() calls to modules, determining whether to use a package's "browser" field or not. By default, the target is 'node'.

The { dynamic } option (default true) when enabled will gracefully skip expressions that cannot be statically evaluated. If you set this to false, then the build will fail and throw an error when it reaches an expression that cannot be evaluated at build time.

File Watching & Re-Compilation

Since this introduces a new dependency in your graph at build-time, it might not get picked up by file watchers like watchify, budo, webpack, et al.

This seems to be a limitation in the babel + bundler bridge; see here.

To get around this in Browserify, you can use brfs-babel which replaces brfs.

watchify index.js -t brfs-babel

Contributing

This module only supported a limited subset of fs. In future, it would be nice to support more features, such as readFile and readdir. Please open an issue if you would like to help contribute.

License

MIT, see LICENSE.md for details.