GOV.UK Prototype Kit

The kit features a plugin subsystem that allows you to extend its capabilities by adding npm packages.

To create a plugin, your npm package must include a govuk-prototype-kit-config.json manifest file. The kit detects this file and exposes the files described within the manifest to the prototype. This is commonly used to share custom layouts, templates, or other assets across multiple prototypes.

Whether you need to follow the standardjs linting rules depends on your goal:

• Submitting a Pull Request: If you intend to contribute code to the GOV.UK Prototype Kit repository, your code must pass the linter.
• Using the Kit in your own project: If you are simply using the kit as a base for a separate project, you are not required to use standardjs or any specific linting rules.

When deploying a prototype to a live environment, use the npm start command. This runs a hardened production configuration designed for security and stability.

Security requirements for online hosting:

• Password Protection: Prototypes hosted online must be password-protected to prevent unauthorized access and keep them hidden from search engines.
• HTTPS: Prototypes must use HTTPS to ensure secure communication.

Installation instructions vary depending on your technical background:

• Non-technical users: Follow the Getting Started guide.
• Developers (Technical): Follow the Advanced Installation guide.

Always refer to the official documentation site for the latest version and setup procedures.

The GOV.UK Prototype Kit uses standardjs to ensure JavaScript code follows consistent conventions. You can manually trigger a lint check across the entire codebase using the provided npm script.

npm run lint

To target a specific major version for a support release, you must use the correct support branch.

To check out an existing branch:

git checkout support/<MAJOR_VERSION>.x

To create a new support branch from a specific tag: If the branch does not exist, fetch all tags and create it from the last released version:

git fetch --all --tags --prune
git checkout tags/v<LAST_RELEASED_VERSION> -b support/<MAJOR_VERSION>.x

Example: git checkout tags/v12.1.1 -b support/12.x

To catch errors in real-time, you can install standardjs plugins for your editor. This allows the linter to run automatically on a per-file basis as you work.

### Sublime Text
Using Package Control, install:
- SublimeLinter
- SublimeLinter-contrib-standard
- StandardFormat (for automatic formatting on save)

### Atom
Install:
- linter-js-standard
- standard-formatter (for automatic formatting)
- standardjs-snippets (for snippets)

### Other editors
Refer to the official StandardJS guides for other popular editors: http://standardjs.com/index.html#text-editor-plugins

To start working on your prototype locally with hot-reloading and development features enabled, use the npm run dev command.

When running in development mode:

• The kit starts an HTTP server at localhost:3000 (or the next available port if 3000 is taken).
• Templates located in app/views/<name>.html are automatically rendered at the URL path /<name>.
• Assets in app/assets are served under /public.
• Sass stylesheets in app/assets/stylesheets/*.scss are compiled and served at /public/stylesheets.
• Browsersync is used to automatically reload your browser whenever you change templates, Sass, or JavaScript files.

When preparing a formal release from a support branch, follow these steps to ensure versioning consistency:

1. Create Release Branch: From support/<MAJOR_VERSION>.x, create a branch named support-release-[version-number] (e.g., support-release-12.1.1 for a fix).
2. Environment Setup: Run nvm use and npm install.
3. Update Versioning Files:
   • CHANGELOG.md: Change the 'Unreleased' heading to the new version (e.g., 12.0.1 (Fix release)) and add a new 'Unreleased' heading above it.
   • VERSION.txt: Update to the new version.
   • package.json: Update the version field.
   • update.sh: Update the VERSION variable (if present).
4. Finalize: Run npm install to update package-lock.json, commit, and open a PR targeting support/<MAJOR_VERSION>.x.

If you require more control over the prototype generated from your local kit package, you can manually create one in an empty directory. Use npx pointing to the path of your local prototype kit and use the --version local flag to ensure it uses your local source instead of the published npm package.

npx ../location-of-your-local-prototype-kit-package create --version local

If you publish your prototypes online, you must protect them with a password. This prevents members of the public from mistaking prototypes for live GOV.UK services.

Important Security Note: While prototypes look like GOV.UK, they do not have the same security provisions as live services. You must ensure user privacy is protected and user data is handled appropriately at all times.