1 | # @artsy/express-reloadable
|
2 |
|
3 | When developing a Node app it's common to rely on tools like [`node-dev`](https://github.com/fgnass/node-dev) or [`nodemon`](https://github.com/remy/nodemon) to make the development process more rapid by automatically restarting the server instance on file-change. What `express-reloadable` does is listen for source-code changes within a subset of your app and, scanning Node's internal module cache, clears the `require` call if found. This tricks Node into thinking the module has not yet been loaded, effectively hot-swapping out your code without a full restart. Additionally, when the `watchModules` option is passed, `express-reloadable` will listen for changes to NPM module code and reload on change. Useful when working with `yarn link` across packages / repos. Crazy-fast development speed!
|
4 |
|
5 | > **Disclaimer**: While this works for most of our use-cases, this is an example of "`require hacking"` and hasn't been tested in all environments. Your mileage may vary.
|
6 |
|
7 | **How it works**:
|
8 | - `express-reloadable` is called with a path to an app, which it then mounts
|
9 | - When source-code within that folder / app changes an internal lookup is made to Node, scanning its `require` cache for the changed file
|
10 | - If found, it is cleared internally via `delete require.cache[id]`
|
11 | - When a new request is made `express-reloadable` executes a callback that re-requires the code and changes are instantly available.
|
12 |
|
13 | **Installation**:
|
14 |
|
15 | ```sh
|
16 | yarn add @artsy/express-reloadable
|
17 | ```
|
18 |
|
19 | **Example**:
|
20 |
|
21 | The below example assumes that the folders `/api` and `/client` exist, and that each contain an index file that exports a mountable express.js route.
|
22 |
|
23 | ```js
|
24 | import express from 'express'
|
25 | import { createReloadable, isDevelopment } from '@artsy/express-reloadable'
|
26 |
|
27 | const app = express()
|
28 |
|
29 | if (isDevelopment) {
|
30 |
|
31 | // Pass in `app` and current `require` context
|
32 | const mountAndReload = createReloadable(app, require)
|
33 |
|
34 | // Pass in the path to an express sub-app and everything is taken care of
|
35 | mountAndReload(path.resolve(__dirname, './client'))
|
36 |
|
37 | // Full example:
|
38 | app.use('/api', mountAndReload(path.resolve(__dirname, './api')), {
|
39 |
|
40 | // If you need to mount an app at a particular root (`/api`), pass in
|
41 | // `mountPoint` as an option.
|
42 | mountPoint: '/api',
|
43 |
|
44 | // Or if you're using `yarn link` (or npm) to symlink external dependencies
|
45 | // during dev, pass in an array of modules to watch. Changes made internally
|
46 | // will be instantly available in the app. Additionally, using something like
|
47 | // `glob`, other modules outside of express route path can be passed.
|
48 | watchModules: [
|
49 | '@artsy/reaction',
|
50 | '@artsy/artsy-xapp'
|
51 | ]
|
52 | }))
|
53 |
|
54 | // If prod, mount apps like normal
|
55 | } else {
|
56 | app.use('/api', require('./api')
|
57 | app.use(require('./client')
|
58 | }
|
59 |
|
60 | app.listen(3000, () => {
|
61 | console.log(`Listening on port 3000`)
|
62 | })
|
63 | ```
|
64 |
|
65 | **Troubleshooting**:
|
66 |
|
67 | > Help! I've mounted my app using reloadable but I'm not seeing any changes?
|
68 |
|
69 | For the utility to work you need to a) ensure that `NODE_ENV=development` (for safety) and b) the path to your app is absolute:
|
70 |
|
71 | ```js
|
72 | // Incorrect
|
73 | app.use(reloadAndMount('./path/to/app'))
|
74 |
|
75 | // Correct
|
76 | app.use(reloadAndMount(path.resolve(__dirname, 'path/to/app')))
|
77 | ```
|
78 |
|
79 | **Thanks**:
|
80 |
|
81 | This package was heavily inspired by @glenjamin's [ultimate-hot-loading-example](https://github.com/glenjamin/ultimate-hot-reloading-example).
|