Should I include or exclude *.bs.js files in git?


#1

This is a pretty common question in Discord chat and I hate to answer it everytime so let’s me type it once and refer to it later.

Should I?

Include

If you’re in the process in introducing ReasonML/Bucklescript into an existing Javascript/Typescript/Flow codebase and you don’t want to change your build process. Everyone who’s not working with ReasonML shouldn’t notice a thing.

The downside of this approach is git conflicts. It’s a real pain.

Exclude

  • You’re starting a project from scratch with ReasonML.
  • You let everyone working on the project know about it. They must install bs-platform for compiling .re files to *.bs.js

If I’m releasing a library for ReasonML consumers, should I?

Exclude it please.

cc @chenglou Please make this a wiki so others could edit it.


#2

In my company I just added one step to build process - ‘npm run build-reason’. It builds all *.bs.js files, which are later imported by ‘normal’ TS/JS application, without even knowing they come from ReasonML code. This build step takes a second, so no one noticed it.

Also, if you exclude bs.js from git, and add a tiny build step ‘npm run build-reason’, you will never forget to commit *.re files together with updated *.bs.js files! In other cases you might update *.re files but forget to build and commit *.bs.js files :frowning:


#3

This is what I’m talking about in include section. and IHMO, the best time to run the script is on git-hooks. This ensures *.bs.js files are always in sync with *.re code.

husky is an amazing tool for introducing git hooks into your codebase


#4

Made into a wiki. When this is mature, let’s upstream it into https://reasonml.github.io/docs/en/project-structure.html#publishing or something. Such thing should be part of the official docs!


#5

This is an interesting question. I think there is an argument to be made that even if a package is only consumed from Reason/Bucklescript that being able to easily see diffs of the generated javascript aids in code review. One could check generated js into git but exclude it from the published package with .npmignore. Reason-React commits and publishes its generated js, for example. I have been doing the same with packages I maintain.

On a side note, I wish bsb had a flag to skip dead code elimination so we wouldn’t have to write code that uses all of our bindings just to see if it generates correct-looking js.


#6

I’ve learnt to trust bsb completely. I never look into bs.js files. I only do that when I think there is a bug in the bindings


#7

I second this. I haven’t looked at a *.bs.js file in months.


#8

I, too, don’t actually read the generated files much nowadays. Doesn’t help much that ReasonReact’s output is rather bad. Though I do think it’s an invaluable tool for newcomers, and a workflow that we, as folks who have been using Reason for a while, don’t encounter enough, since our our codebase likely overcame the initial interop period.

So it depends on the condition of your company’s codebase, etc.


#9

For just being able to see how a given change affects the compiled output I think tooling can help. If you snapshot (but don’t commit) the JS artifacts on your master branch, then you can run a quick diff of the changes on the feature branch. Maybe even add that to the scripts in your package.json. Then you get all the benefits of being able to see the changes without creating a bunch of noise in commits and further complicating merge conflicts. I think I’ll give this setup a try, actually.