| 1 |
|
| 2 | Modules and Inheritance
|
| 3 | =======================
|
| 4 |
|
| 5 | At Springer Nature, we have a lot of code that we need to share between different applications. To do that, we enabled Shunter to pull in common resources, filters, helpers and templates from one or more declared npm modules. These modules are loaded in as dependencies via `package.json` and the application is made aware of them by configuration options set in `config/local.json`.
|
| 6 |
|
| 7 | In this way, shared code rollout can be controlled through versioning, which reduces the risk of regressions.
|
| 8 |
|
| 9 | Code loaded in through modules can be overridden by your application simply by having a file of the same name in your application.
|
| 10 |
|
| 11 | Set-up Steps
|
| 12 | ------------
|
| 13 | 1. Set up your shared code with the same structures as you have for your main app, e.g. templates are put into a `view` folder, JavaScript goes into a `resources/js` folder, etc.
|
| 14 | 1. In your application's `package.json`, add your sharing module to dependencies, e.g.
|
| 15 | ```js
|
| 16 | "dependencies": {
|
| 17 | "shunter": "^1",
|
| 18 | "my-shared-module": "~1.0"
|
| 19 | },
|
| 20 | ```
|
| 21 | 1. Add the module name to `config/local.json`, e.g.
|
| 22 | ```json
|
| 23 | {
|
| 24 | "modules": ["my-shared-module"]
|
| 25 | }
|
| 26 | ```
|
| 27 | 1. Run `npm install` to add in the code
|
| 28 |
|
| 29 | Private Modules
|
| 30 | ---------------
|
| 31 | We are using a private repository for versioned node modules so that we can use version ranges in `package.json` ([Gemfury](https://gemfury.com/)).
|
| 32 |
|
| 33 | It isn't essential to use this - you can still use the other methods of setting your module location like GitHub urls. However without a repository you are limited to pointing to one specific version.
|
| 34 |
|
| 35 | Config
|
| 36 | ------
|
| 37 | When Shunter sets up configuration, it looks in your app's folders for `config/local.json` and extends the default config options object with the object found in the `local.json` file.
|
| 38 |
|
| 39 | If there is a `modules` property with an array with one or more item in it, this is used within Shunter to find the relevant directory under `node_modules` and from there to load in Dust templates and helpers, add the resources files to the asset handler load path, and apply filters.
|
| 40 |
|
| 41 | Overriding shared code
|
| 42 | ------------------------------
|
| 43 | If your shared code module and your app have a file of the same name, Shunter will pick the file in your app over the one in your shared code module.
|
| 44 |
|
| 45 | E.g.
|
| 46 | If you have both `my-shared-module/resources/css/forms.css` and `my-app/resources/css/forms.css`, CSS in the `my-shared-module` version will not be loaded into the compiled `main.css` file.
|
| 47 |
|
| 48 | Developing with your module
|
| 49 | ---------------------------
|
| 50 |
|
| 51 | Use NPM to point to your locally checked-out module code with [npm link](https://docs.npmjs.com/cli/link)
|
| 52 |
|
| 53 | Testing your code
|
| 54 | ------------------------
|
| 55 | You can run tests on your code in the same way as you do for your application.
|
| 56 |
|
| 57 | The module's dev dependencies should include Shunter so that the rendering helper is available (see [Testing](testing.md))
|
| 58 |
|
| 59 | ---
|
| 60 |
|
| 61 | Related:
|
| 62 |
|
| 63 | - [Full API Documentation](index.md)
|