CoCalc's Static Frontend Webapp Assets

Using webpack we build the static assets that run in the client's browser.

The npm run scripts

1. Development

When doing development, use npm run webpack and npm run tsc in two terminals.

npm run weppack
npm run tsc

ALSO, run npm run tsc in the packages/frontend directory, if you are editing that code.

The first runs webpack to package everything up, the second independently checks for errors in the typescript files in the frontend package (the two should not interfere in any way with each other), and the third does the same for code in packages/static/src. If you're using an editor like vscode that tells you Typescript errors, you don't need to bother with npm run tsc-*.

Use npm run webpack-prod to build and test the production version locally:

npm run webpack-prod

This is the same as npm run webpack, but with more aggressive chunking, caching, minification, etc. It's a good idea to test this before making a release, in case something surprising changes. Also, check in the Network tab of Chrome dev tools that loading cocalc doesn't transfer too much data (e.g., due to installing a huge package).

If you get really weird errors that make no sense, the on-disk cashing may be broken. In that case, delete it and restart webpack:

rm -rf /tmp/webpack

2. Measuring size

Run npm run webpack-measure and when it finishes, look at dist-measure/measure.html for an interactive graphic that shows how much space each part of CoCalc is using. Use npm run webpack-measure-prod to see what the situation is for the production build.

It's often useful to do:

ls -lh dist/*.js |more

3. Making a release to npmjs

Make sure to kill any running webpack first. Everything to make a release is automated by going to ~/cocalc/src and using npm run publish ...:

$ cd ../..
$ pwd
/home/user/cocalc/src
$ time npm run update-version --packages=static --newversion=minor
$ time npm run publish --packages=static

Here newversion could be major, minor, or patch. This does a full production build, updates the version in package.json, then pushes the result to npmjs.com, and commits the change to package.json to git.

If you want to make a development release, e.g., to make it easier to debug something on test.cocalc.com, do

time NODE_ENV=development npm run publish --packages=static

More about development

First we assume you have installed all dev dependencies everywhere for all modules (npm ci; npm run build). To do interactive development on CoCalc, you start webpack and typescript in watch mode as follows:

To do development, in one terminal session (in this package/static directory!) start webpack running

npm run webpack

As you edit code, this quickly shows any errors webpack finds in bundling all your code up.

In a second terminal (also in this package/static directory!), start watching for errors via typescript:

npm run tsc-frontend

The files that are produced by webpack, and that your hub serves up are in the subdirectory dist/. The hub server serves these static files to your browser.

If you're editing Typescript files in src/, you should also run

npm run tsc-static

which will check those files for typescript errors.

Landmines to watch out for

The module search path:

If there is a package installed in packages/static/node_modules it will get included by webpack before the same (but different version) package in frontend/node_modules, because of what we listed in resolve.modules in webpack.config.js. This can cause confusion. E.g., maybe an old version of the async library gets indirectly installed in packages/static/node_modules, which is wrong. That's why a specific version of async is installed here. The one good thing about this is it makes it easier to override modules installed in frontend/ if necessary, like we do with pdfjs-dist since otherwise it ends up with its own copy of webpack.

tsconfig.json and code splitting

Code splitting can't work without this tsconfig.json option:

{
  "compilerOptions": {
    "module": "esnext"
  }
}

Changing code in other packages such as packages/util

1. Change something in packages/util.
2. You must do npm run build in packages/util to make the changes visible to webpack! This is because anything outside of packages/util actually only sees packages/util/dist which is the compiled versions of everything. This is a significant change from before.