Oak Web Application

The Oak National Academy Web Application code base.

• Getting started
• Automatic Checks
  • Unit tests
  • End-to-End Browser Tests
  • Pre-commit and Commit Message Hooks
    • Pre-commit
    • Commit Message Validation
• CI/CD
  • Pull Requests and Automated Checks
  • Builds and Deployments
  • Release Mechanism
• External Contributions
  • Security and Bug Bounty
  • Contributing to the Code
• Open Source Acknowledgements

Other documentation can be found in standalone READMEs:

• Build
  • Fetching Config
  • Fetching Secrets
• Components
  • Forms
  • Icon
• Docs
  • Images
  • Testing
  • SEO Meta tags, JSON-LD, sitemaps, robots.txt etc.
• Error Handling
• React Context

Getting started

Create an environment configuration file by running:

cp .env.example .env

Now populate the new file, asking a colleague for the values.

Now install dependencies

npm install

Then, run the development server:

npm run dev

If successful two further config files .env.development.local and .env.local will have been automatically generated. You can access the running web app on http://localhost:3000

Automatic Checks

For more detail please see the test documentation.

Pa11y Tests

We run Pa11yCI in CI to check for deterministic accessibility issues. To run Pa11y locally start the dev server with npm run dev, then in another process run Pa11y with npm run pa11y.

Unit Tests

Unit tests live next to the code they are testing wherever possible. Next does not allow any files under the src/pages/ directory other than routes, so those test file are under the src/__tests_/pages/ directory, mirroring the src/pages file structure.

• npm run test will run the tests using --watch, with coverage statistics disabled.
• npm run test:coverage will run tests using --watch with coverage statistics enabled.
• npm run test:ci will run the tests once and create a coverage report.

End-to-End Browser Tests

We use WebdriverIO.

See the testing docs for further details.

Pre-commit and Commit Message Hooks

We use Husky to run pre-commit and commit message validating hooks, including unit tests, code linting, type checking, and commit message format checking.

Pre-commit

Currently this hook

• Formats the code using Prettier
• Runs style and code linting
• Runs the unit tests

Commit Message Validation

We use Commitlint to validate that commit message meet the conventional commit standard. If you want help with the format you can use the interactive commit message prompt by running the script npm run cc, note you will need to have staged Git changes first or it will error (because there will be nothing to commit).

CI/CD

Pull Requests and Automated Checks

Required Github Secrets for Workflows

TODO

• A_SECRET_VALUE - Some config or tool auth.

Builds and Deployments

The app is built statically, with two caveats.

• On dynamic routes, an empty array and fallback: "blocking" is returned from getStaticPaths. This means that those pages are built on first request, then stored as if they had been built at build time. This allows us to build an app with tens of thousands of pages in a few minutes.
• All pages that use getStaticProps have incremental static regeneration turned on, which re-runs getStaticProps periodically on the server in order to rebuild the page with the latest data.

The upshot of these two pieces of config is that new pages become available automatically when the underlying data is updated, and existing pages get updated data when it is available, all without having to rebuild the app.

Oak preview and production builds are on Netlify.

Required Environment Variables for Builds

Release Mechanism

• All changes to the main branch must happen through pull requests.
• Changes on the main branch trigger the create_semantic_release Github workflow which creates a Github release, and updates the package.json version number. The commit message has a structure set in release.config.js.
• All commits on main will trigger a Vercel deploy, but non-release commits (according to the commit message structure), will be cancelled.
• The Vercel deployment will trigger the deployment_checks Github workflow.

External Contributions

Security and Bug Bounty

Please see our security.txt file.

Contributing to the Code

We don't currently accept external contributions to the code base, but this is under review and we hope to find an approach the works for us and the community.

Open Source Acknowledgements

As will all web projects we are dependent on open source libraries maintained by others. While it is not practical to acknowledge them all, we would nevertheless like to express our gratitude for the contributions and efforts of the OSS community. Our dependency list can be found in our package.json file.

License

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. Where any Oak National Academy trademarks or logos are included, these are not released under the MIT License, and should be used in line with Oak National Academy brand guidelines.

Any documentation included is © Oak National Academy and available under the terms of the Open Government Licence v3.0, except where otherwise stated.