README
bulk-decaffeinate
A tool, backed by decaffeinate, to help you convert some or all of a CoffeeScript codebase to JavaScript.
The tool can check a codebase for decaffeinate-readiness, and once the code (or a part of it) is ready, bulk-decaffeinate can actually run the conversion and some follow-up cleanups. Here's an example of checking the Hubot repo:
> npm install -g bulk-decaffeinate decaffeinate eslint
...
> git clone https://github.com/philc/vimium.git
...
> cd vimium
> bulk-decaffeinate check
Doing a dry run of decaffeinate on 50 files...
50/50
All checks succeeded! decaffeinate can convert all 50 files.
Run "bulk-decaffeinate convert" to convert the files to JavaScript.
> bulk-decaffeinate convert
Verifying that decaffeinate can successfully convert these files...
50/50
Backing up files to .original.coffee...
50/50
Renaming files from .coffee to .js...
50/50
Generating the first commit: "decaffeinate: Rename bg_utils.coffee and 49 other files from .coffee to .js"...
Moving files back...
50/50
Running decaffeinate on all files...
50/50
Deleting old files...
50/50
Setting proper extension for all files...
50/50
Generating the second commit: decaffeinate: Convert bg_utils.coffee and 49 other files to JS...
Running eslint --fix on all files...
50/50
[Skips eslint for all files because there is no config.]
Generating the third commit: decaffeinate: Run post-processing cleanups on bg_utils.coffee and 49 other files...
Successfully ran decaffeinate on 50 files.
You should now fix lint issues in any affected files.
All CoffeeScript files were backed up as .original.coffee files that you can use for comparison.
You can run "bulk-decaffeinate clean" to remove those files.
To allow git to properly track file history, you should NOT squash the generated commits together.
Assumptions
While the underlying decaffeinate tool tries to be general-purpose, bulk-decaffeinate intentionally makes some assumptions about your use case:
- Your build tooling can already handle JavaScript. Replacing a .coffee file with a .js file will "just work" as long as the files are equivalent.
- Adding some extra .original.coffee files as temporary backups won't cause trouble.
- You are using git for source control and all .coffee files being converted are already tracked in the git repo.
- You are using eslint for JS linting and you already have a .eslintrc file specifying your preferred styles.
Feel free to file an issue or submit a PR if these assumptions don't match your current project. Most steps shouldn't be hard to disable using a config setting.
What it does
bulk-decaffeinate supports a number of commands:
check
does a dry run of decaffeinate on the specified files and reports how decaffeinate-ready the set of files is.view-errors
should be run aftercheck
reports failures. It opens the failed files in the online decaffeinate repl, with one browser tab per failed file. Each browser tab loads the online repl page with your source code encoded in the hash fragment of the URL. Because it is in the hash fragment and not a regular query param, your code is never sent to the server.convert
actually converts the files from CofeeScript to JavaScript, generating a commit for each intermediate step.modernize-js
runs only the JS-to-JS transformations on the specified JavaScript files. Unlikeconvert
, this command does not create a git commit.clean
deletes all files with ".original" in the name in the current directory or any of its subdirectories.land
packages multiple commits into a merge commit based on an remote branch (origin/master
by default). Splitting the decaffeinate work into separate commits allows git to properly track file history, but it can create added difficulty after code review is finished, andland
helps with that. Theland
command does not actually push any commits; it just creates a merge commit that is ready to push after a sanity check.If the
phabricatorAware
option is set, theland
command does extra work to make sure that every commit has a "Differential Revision" line and that the final merge commit has the commit description.
Here's what convert
does in more detail:
- It does a dry run of decaffeinate on all files to make sure there won't be any failures.
- It backs up all .coffee files to .original.coffee files, which makes it easily to manually do a before-and-after comparison later.
- It generates a commit renaming the files from .coffee to .js (but not changing the contents). Putting this step in its own commit allows git to track the file history across renames (so, if possible, you should land the changes as a merge commit rather than squashing the commits together).
- It runs decaffeinate on all files and gets rid of the .coffee files, then generates a commit.
- If the
jscodeshiftScripts
config value is specified, it runs jscodeshift with those scripts in the order specified. - If the
mochaEnvFilePattern
config value is specified, it prepends/* eslint-env mocha */
to the top of every test file. - If the
fixImportsConfig
config value is specified, it runs a transform that does whole-codebase analysis to fix any import problems that might have been introduced by decaffeinate. - It runs
eslint --fix
on all files, which applies some style fixes according to your lint rules. For any remaining lint failures, it puts a comment at the top of the file disabling those specific lint rules and leaves a TODO comment to fix any remaining style issues. - If the
codePrefix
config value is specified, it prepends that string to every affected file. - All post-decaffeinate changes are committed as a third commit.
In all generated commits, "decaffeinate" is used as the author name (but not the
email address). This makes it clear to people using git blame
that the file
was generated using decaffeinate, and not necessarily authored by the person who
happened to run the decaffeinate script.
If you want to see the full details, the source code should hopefully be fairly readable.
Configuration
You can specify custom configuration in a config file, usually called
bulk-decaffeinate.config.js
, in the current working directory. It should
export a JS object with your config. Any file starting with bulk-decaffeinate
and ending with .config.js
will be counted, and multiple config files may
exist at once. If there are multiple config files, they are merged, with
alphabetically-later config file names taking precedence over
alphabetically-earlier files.
Alternatively, you may specify the config file location using the --config
option, e.g. bulk-decaffeinate --config ../bulk-decaffeinate.config.js
to use
a config file one level up in the directory structure.
Many config options can also be specified directly as CLI arguments, with CLI arguments taking precedence over any config file setting.
Here's an example config file:
module.exports = {
jscodeshiftScripts: [
'./scripts/dev/codemods/arrow-function.js',
'./scripts/dev/codemods/rd-to-create-element.js',
'./scripts/dev/codemods/create-element-to-jsx.js',
],
mochaEnvFilePattern: '^.*-test.js