DEVELOPING.md

Developing

• How do I setup the project for development?
• What's the development workflow?
• Why do my files automatically change?
• I can't make a "Work in progress" commit because the build is broken
• Why are the dev tools scripts so verbose?
• Why are there so many config files?
• Why isn't the build bundled or minified?
• Why does the Babel build script contain the --source-maps option?
• Why does the format-eslint script ignore errors?
• Why does the start-src script use --require node_modules/dotenv/config?

How do I setup the project for development?

1. If you don't have write access to this repo, fork it
2. Clone the repo
3. Install dependencies: npm ci
4. Ensure everything is working: npm run validate
5. Use VS Code? Run command Extensions: Show Recommended Extensions and install

What's the development workflow?

1. Create a system-wide link for use in other directories: npm link

2. Start develop mode: npm run dev

3. For TDD fans: npm run test--watch

4. Write code

5. Create new temporary directory to test app population named create-exposed-app-test-my-new-feature

6. Run npx create-exposed-app in new directory

   Note: This should reference your local create-exposed-app copy, setup by previous linking command

7. Create a pull request on GitHub

8. Remove the system-wide link: npm unlink

9. Remove the temporary test directory create-exposed-app-test-my-new-feature

Why do my files automatically change?

See ADR-005: Format Files and ADR-006: Format Files Programmatically.

I can't make a "Work in progress" commit because the build is broken

Include the --no-verify option during the commit:

git commit -m "WIP" --no-verify

Why are the dev tools scripts so verbose?

See ADR-002: Prefer Configurable Dev Tools.

Why are there so many config files?

See ADR-003: Prefer Multiple Config Files.

Why isn't the build bundled or minified?

See ADR-004: Minimally Transform Source Code During Build.

Why does the Babel build script contain the --source-maps option?

This option is available in the Babel config file (sourceMaps: true), but has diffrent behaviour. Only the command line supports the creation of .map files. See babel/babel#5261.

Why does the format-eslint script ignore errors?

Linting errors should not be reported when formatting, that it was the lint command is for.

Errors are ignored by appending the following: >/dev/null 2>&1 || true.

Why does the start-src script use --require node_modules/dotenv/config?

The recommended setup advises preloading with --require dotenv/config. However due to a known problem in Babel, this must be prefixed with node_modules.