transpilify's Introduction

transpilify

Applies browserify transforms to your source code, without actually bundling it.

This is useful if you have a module that would typically use some browserify transforms (like glslify or browserify-css), but you would like to publish a bundler-agnostic distribution to npm.

work in progress

This module is still a work in progress and may be subject to more changes.

Install

With npm:

npm install -g transpilify

API Usage

`transpile = createTranspiler([opt])`

Returns a function, transpile, which creates a transform stream. The options:

transform a transform or array of transforms, same usage as browserify
basedir the base directory used to resolve transform names from

The transform elements can be a string (local dependency) or function (conventional transform stream). You can use a tuple to specify the transform and its options. For example:

var transpiler = createTranspiler({
  transform: [
    // local dependency
    'brfs',
    // transform + options
    [ 'glslify', { transform: [ 'glslify-hex' ] },
    // transform function
    require('babelify').configure({
      presets: [ 'es2015' ]
    })
  ]
})

`stream = transpiler(filename)`

Creates a new transform stream for the given filename, reading it from disk.

For example:

var createTranspiler = require('transpilify')
var transpiler = createTranspiler({
  transform: 'brfs'
})

transpiler('src/index.js')
  .pipe(process.stdout)

CLI Usage

Accepts a single file (to stdout or --out-file) or a single directory (to --out-dir).

# to stdout
transpilify src/index.js [opts]

# to file
transpilify src/index.js --out-file build.js [opts]

# transpile whole directory
transpilify src/ --out-dir dist/ [opts]

Options:

--transform, -t are written like browserify CLI transforms; supports subarg
- e.g. --transform brfs
--out-file, -o write results to a file
--out-dir, -d transpile directory & contents to destination
--ignore, -i a pattern or array of glob patterns to ignore (will not emit files matching these globs)
--extensions, -x
- a list of comma-separated extensions to accept for transformation
- defaults to ".js,.jsx,.es6,.es"
--quiet do not print any debug logs to stderr

Browserify Examples

For example, we have a Node/Browser index.js file:

var fs = require('fs')
var str = fs.readFileSync(__dirname + '/hello.txt', 'utf8')
console.log(str)

And our static file:

Hello, world!

After installing brfs locally as a devDependency, we can transpile:

transpilify index.js --transform brfs > dist/index.js

The resulting dist/index.js file will have the contents statically inlined, without any additional overhead of a traditional bundler.

console.log("Hello, world!")

Another example, using babelify and presets:

transpilify index.js -t [ babelify --presets [ es2015 react ] ] > bundle.js

Custom Transform Example

Say you want a simple transform for your Node/Browser/whatever module, without the complexities of a bundler, babel plugins, or what have you.

Add a transform:

// uppercase.js
var through = require('through2')
module.exports = function (filename) {
  return through(function (buf, enc, next) {
    next(null, buf.toString().toUpperCase())
  })
}

Now you can reference the uppercase.js file during transpilation:

transpilify index.js -t ./uppercase.js

This will uppercase your entire source file.

Roadmap / TODO

Investigate better source map support

transpilify's People

Contributors

Stargazers

Watchers

transpilify's Issues

When using on folder with more than 30 files, some files are not written to disk

When using cli.js on a folder containing more than 30 files (not an exact number), some files at the end of the alphabetic list are not written to disk at the end of the process.

step to reproduce

clone this branch: https://github.com/autra/transpilify/tree/bug_missing_files
execute node ./test/index.js

expected

cli usage: check directory call is successful

actual

this test fails, because some fils are not created in tmp. On my machine, the skipped files are test[6-9].js, so the 4 last (in lexicographic order).

I also reproduce this issue with a far larger repo (this one)

I am currently investigating the problem, but I have no clue yet*, so better sharing this, in case you have an idea!

(* well, my intuition tells me it's a stream problem. I might not be called or flushed properly...)

Configuration / More Features

Ok, I've pushed some more stuff. Now it's using multipipe (I was getting an error with pump when not enough streams were given, not sure if relevant anymore though) and vinly-fs to try and mimic the Babel directory transpiling. Some --extensions and --ignore flags also added to CLI, these also affect single file transpiling.

The next question is how to handle configuration, and whether it's even necessary. We can look for a package.json "transpilify" flag which behaves just like browserify. I don't think we need to deal with dependencies since this is only aiming to transpile local source files.

{
  "transpilify": {
      "transform": [ "brfs" ]
  }
}

Alternatively we could use .transpilifyrc to avoid polluting package.json meta data.

I also wonder if a tool like this might be able to help fix some of the issues with npm link + browser dev (e.g. budo/beefy) across several modules that need transpiling on pre-publish (es2015, brfs or whatever).

The API could be changed slightly to be a true browserify transform: createTranspiler(file, opt).

I'm not sure yet what that would add. Maybe there is another approach, involving using "browserify" config during dev, but removing/disabling it for pre-publish to npm. Complicated... 😕

/cc @hughsk

mvp

@mmckegg we talked about making this module, so i made a repo here, we can implement it or not as we want.

the basic idea is to use require.extensions to transpile modules on require with browserify transforms.

notes:

require.extensions docs, code.
browserify transform docs.

an open question is what the API should be, considering that require.extensions expects file extensions, whereas browserify transforms handle every file. a simple proposal:

require('transpilify')({
  '.js': [
    'evalify'
  ]
})

then have analogous settings in the package.json, so you can run require('transpilify')() to default using those settings.

thoughts on this?

Recommend Projects

ahdinosaur / transpilify Goto Github PK