@cocalc/static

# 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. ```sh 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: ```sh 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: ```sh 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: ```sh 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 ...`: ```sh $ 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](http://test.cocalc.com), do ```sh 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 ```sh 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: ```sh 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 ```sh 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](https://davidea.st/articles/webpack-typescript-code-split-wont-work) without this tsconfig.json option: ```js { "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.