experience-monks / babel-plugin-static-fs

statically transforms Node fs for the browser

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.

babel-plugin-static-fs's Issues

Remove `path` if unused in scope?

Not sure if this is dangerous. The path module does not have any side-effects that I know of, so we could remove it entirely from the program when the only usage has been stripped out. This would significantly reduce bundle size in browserify if you aren't already requiring path/process/etc. However, it might introduce an unexpected change for the end user.

Example integration with webpack

Hi, I'm new to webpack. I wanted to inline my fs.readFileSync statements but I don't know how to integrate this plugin into webpack. Can you guide me?

Support require.resolve calls.

This is handy for inlining docs and such IE:

const readmeMD = fs.readFileSync(require.resolve('lodash/README.md'), 'utf8')

Also things like libraries that expose css.

const style = fs.readFileSync(require.resolve('highlight.js/styles/ocean.css'), 'utf8')

Deal with source maps a bit nicer

Ideally when you look in Chrome DevTools you should not see the fs.readFileSync call... Or should you? Not sure.

Doesn't like dynamic imports

Plugin is fine when using without dynamic imports in Webpack – using chunkFilename. However, as soon as you try to build it with dynamic imports I get:

ERROR in ./node_modules/pdfkit/js/document.js
Module build failed: Error: /node_modules/pdfkit/js/document.js: Could not statically evaluate how the fs module was required/imported.

delete

delete

Fix Buffer Deprecation Warnings

Node version: 12.11

Deprecation message:

DeprecationWarning: Buffer() is deprecated due to security and usability issues. Please use the Buffer.alloc(), Buffer.allocUnsafe(), or Buffer.from() methods instead.

I think the issue is self-explanatory, we can probably use Buffer.from instead and it should address this.

Does not work with __coverage__ or istanbul

I get this error

Error: file.js: Could not statically evaluate how the fs module was required/imported. while parsing file: file.js

When trying to use static-fs with either babel-plugin-static-fs or babel-plugin-istanbul

Do not bail-out when a static problem is found

A file can have a mix of dynamic and static fs.readFileSync, and when a dynamic read is found, throws and error and stops the build.

Simply, if a dynamic read is found, it should continue with the next one, as is not a terminal error actually.

I've modified static-eval.js it to achieve this with:

Is a ugly workaround, but I had to test if this works. It worked.

Maybe there's a better way to achieve this.

How to bust the Babel cache?

Thanks for this great plugin.

I'm getting a problem where it doesn't seem to pick up changes to the file being inlined. I have to edit the parent JS file to cachebust it. I think this is because the parent file is stuck in Babel's cache with the inlined string, and Babel doesn't know that the underlying file has changed.

Is there any solution to this? Currently I am having to make an arbitrary whitespace change in the parent file whenever I want to edit the child file. (Excuse terminology.)

Add the ability to modify filename during build

We have onFile example, but it doesn't seem to be too useful. What would be great is to have something like this:

gulp.task('some', () => {
  return gulp.src([pathMap.src + '/**/*.js'])
    .pipe(babel({
      plugins: [[staticFs, {
        onFile: filename => {
          return join(pathMap.images, filename)
        }
      }]]
    }))
    .pipe(gulp.dest(pathMap.dist));
});

This way we won't have to do

readFileSync(join(__dirname, '../../../../../src/image1.png'));
//...
readFileSync(join(__dirname, '../../../../../src/imageN.png'));

instead

readFileSync('image1.png');
//...
readFileSync('imageN.png');

Is that possible?

readFile should not trigger error

Currently, using fs.readFile produces an error if the file cannot be statically linked.

babel-plugin-static-fs should not be invoked when fs.readFile is called if it does not support it.
This makes the plugin useless if you aren't only statically importing files.

Emit file dependencies

So watchify can pick up on things

why store in a Buffer?

Hi,

simple question: why does the string need to be stored in a Buffer? it could be cross-browser to store it just as a string, since Base64 is just a string.

fs is not defined when wrapped inside promisify

The const fs = require('fs') line gets stripped when using fs inside a function, (in this case promisify), leading to fs is not defined error:

test.js:

const fs = require("fs");
const { promisify } = require("util");
const writeFileAsync = promisify(fs.writeFile);`

npx babel --plugins=babel-plugin-static-fs test.js > out.js

out.js:

const {promisify} = require("util");
const writeFileAsync = promisify(fs.writeFile);

Incompatible with babel 7

Using this plugin with Babel 7 results in this error:

Cannot read property 'traverse' of null

It seems like path.getFunctionParent()'s behavior has changed for babel 7.