|
| 1 | +# Primer Development |
| 2 | + |
| 3 | +If you've made it this far, **thank you**! We appreciate your contribution, and hope that this document helps you along the way. |
| 4 | + |
| 5 | +## Structure |
| 6 | +The project is structured as a [monorepo] made up of lots of small npm modules, many of which depend on each other. We use [Lerna] to manage, version, and publish all of the packages together. |
| 7 | + |
| 8 | +The top-level `package.json` is not published, but tracks common dependencies for developing Primer, and hosts some useful npm [run-scripts]. See the [scripts section](#scripts) for more info. |
| 9 | + |
| 10 | +## Workflow |
| 11 | +The typical Primer workflow looks something like this: |
| 12 | + |
| 13 | +1. [Install](#install) |
| 14 | +2. [Start Storybook](#storybook) |
| 15 | +3. Navigate to the module you're working on and modify the SCSS and/or markdown files. |
| 16 | +4. Test your changes in Storybook. |
| 17 | +5. Push your work to a new branch to test it on Travis and have it reviewed by the Primer "core" team. |
| 18 | + |
| 19 | +## Install |
| 20 | +Run `npm install` to install the npm dependencies and automatically run link all of the local packages together with `npm run bootstrap`. |
| 21 | + |
| 22 | +### Troubleshooting install problems |
| 23 | +If you run into trouble installing, it's always best to ensure that you're starting from a clean slate by running the following from the repository root directory: |
| 24 | + |
| 25 | +```sh |
| 26 | +npm run fresh |
| 27 | +``` |
| 28 | + |
| 29 | +If _that_ gives you problems, then you can try manually deleting everything and starting over: |
| 30 | + |
| 31 | +``` |
| 32 | +rm -rf node_modules |
| 33 | +rm -f package-lock.json */*/package-lock.json |
| 34 | +npm install |
| 35 | +``` |
| 36 | + |
| 37 | +**You may need to do this whenever switching between branches with different dependencies, submodules, or versions of Node and/or npm.** The Primer core team generally uses the latest major version of Node (10 as of this writing), but our CI tests run Node 8 and npm 6. You can check which versions you're running with: |
| 38 | + |
| 39 | +```sh |
| 40 | +npm --version |
| 41 | +node --version |
| 42 | +``` |
| 43 | + |
| 44 | +## Storybook |
| 45 | +Run `npm start` to start up [Storybook], then visit [localhost:3000](http://localhost:3000) to test your work. By default, all `html` code blocks of all `*.md` files in each module will be rendered as stories and listed under the module's name in the left-hand nav. File changes should trigger live reload automatically after a brief delay. |
| 46 | + |
| 47 | +If the package you're working on has a `stories.js`, it probably includes a snippet like this: |
| 48 | + |
| 49 | +```js |
| 50 | +const stories = storiesOf('Module name', module) |
| 51 | + |
| 52 | +storiesFromMarkdown(require.context('.', true, /\.md$/)) |
| 53 | + .forEach(({title, story}) => { |
| 54 | + stories.add(title, story) |
| 55 | + }) |
| 56 | +``` |
| 57 | + |
| 58 | +This is how we find all of the Markdown files in the package directory and generate stories from their code blocks. Storybook sections are labeled by the first argument to `storiesOf()` (in the above example, "Module name"), and individual stories get their titles from either the previous Markdown heading or the `title` attribute in the fenced code block. See the [`code-blocks` docs](https://npmjs.com/package/code-blocks) and the [`storiesFromMarkdown()` source](./.storybook/lib/storiesFromMarkdown.js) for more info. |
| 59 | + |
| 60 | +## CSS packages |
| 61 | +All of the Primer CSS packages live in the [modules](./modules) subdirectory, including the [`primer`](./modules/package) omnibus package. |
| 62 | + |
| 63 | +## Tools |
| 64 | +Many tools specific to development of Primer CSS live in the [tools](./tools) subdirectory. |
| 65 | + |
| 66 | +## Scripts |
| 67 | +The [`script` directory](./script) houses a collection of scripts that we use to maintain, test, build, and publish packages. Some scripts of note: |
| 68 | + |
| 69 | +* `script/check-imports` compares the list of Primer npm dependencies for each package with SCSS `@import` statements in its source, and warns if any mismatches (dependencies without corresponding imports, or vice-versa) are found. |
| 70 | +* `script/compare-published` compares the latest published versions of each Primer CSS package with the `version` field in its local `package.json`, and reports any discrepancies. |
| 71 | +* `script/get-packages` lists all of the package subdirectories from both `modules` and `tools` directories, and is useful for iterating in shell scripts: |
| 72 | + |
| 73 | + ```sh |
| 74 | + for pkg in $(script/get-packages); do |
| 75 | + echo $pkg |
| 76 | + done |
| 77 | + ``` |
| 78 | + |
| 79 | + If you're looking for more detail, you can also run `npx lerna ls`, which will list the packages by name along with their versions. |
| 80 | + |
| 81 | +Scripts like `lint-scss`, `notify`, and `test-docs` are called from individual packages to run specific common tasks; `npm-run` and `npm-run-all` are used more generally to run monorepo-installed npm utilities within the package directory, and can probably be refactored to simply run [npx]. |
| 82 | +
|
| 83 | +
|
| 84 | +[monorepo]: https://github.com/babel/babel/blob/master/doc/design/monorepo.md |
| 85 | +[Lerna]: https://github.com/lerna/lerna |
| 86 | +[run-scripts]: https://docs.npmjs.com/cli/run-script |
| 87 | +[Storybook]: https://storybook.js.org/ |
| 88 | +[npx]: https://www.npmjs.com/package/npx |
0 commit comments