├── CODE_OF_CONDUCT.md ├── LICENSE ├── README.md ├── decision-records ├── 000-template.md ├── 001-javascript-for-less-capable-browsers.md ├── 002-restructure-based-on-single-package.md ├── 003-templating-languages.md ├── 004-new-version-font.md ├── 005-repository-organisation-for-v5.md ├── 006-javascript-compatibility.md ├── 007-javascript-file-formats.md ├── 008-reset-the-javascript-api.md ├── 009-throw-errors-component-constructors.md ├── 010-remove-init-method.md └── README.md └── proposals ├── 000-template.md ├── 001-use-rfcs-and-adrs-to-discuss-proposals-and-record-decisions.md ├── 002-publish-one-npm-package-instead-of-multiple-npm-packages.md ├── 003-make-override-classes-consistent.md ├── 004-enable-importing-css-modules-via-filename-convention-used-in-common-frameworks.md ├── 005-namespace-govuk-frontend-nunjucks-sass-using-a-nested-folder-structure.md ├── 006-initialise-javascript-using-govuk-namespaced-data-module-attributes.md ├── 008-simplifying-imports-to-improve-compilation-performance.md └── README.md /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | ## Code of Conduct 2 | 3 | This project follows the ['alphagov' GitHub organisation Code of Conduct][coc]. 4 | 5 | [coc]: https://github.com/alphagov/code-of-conduct 6 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 Crown Copyright (Government Digital Service) 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # GOV.UK Design System Architecture 2 | 3 | We use this repository as a forum to discuss and record technical decisions that 4 | affect the products supported by the GOV.UK Design System team, including: 5 | 6 | - GOV.UK Design System 7 | - GOV.UK Frontend 8 | - GOV.UK Prototype Kit 9 | 10 | This repository is open to enable involvement from the wider community and as a 11 | reference for other teams within GDS and wider government. 12 | 13 | There are 2 types of documentation: 14 | 15 | - [Proposals](/proposals), often referred to as 'requests for comments', which 16 | allow us and the wider community to suggest and refine ideas. 17 | - [Decision Records](/decision-records), which document decisions that have been 18 | made, along with any context. 19 | 20 | ## Code of Conduct 21 | 22 | This project follows the ['alphagov' GitHub organisation Code of Conduct][coc]. 23 | 24 | [coc]: https://github.com/alphagov/code-of-conduct 25 | -------------------------------------------------------------------------------- /decision-records/000-template.md: -------------------------------------------------------------------------------- 1 | # [Decision Title] 2 | 4 | 5 | **Date:** 6 | 7 | **Status:** 8 | 9 | ## Decision 10 | 11 | 12 | 13 | ## Rationale 14 | 15 | 16 | 17 | ## Risks and constraints 18 | 19 | 20 | 21 | ## Alternatives considered 22 | 23 | 24 | 25 | ## Implications 26 | 27 | 28 | 29 | ## Contributors 30 | 31 | 32 | 33 | ## Associated issues and pull requests (PRs) 34 | 35 | 36 | 37 | ## Outcomes 38 | 39 | 40 | -------------------------------------------------------------------------------- /decision-records/001-javascript-for-less-capable-browsers.md: -------------------------------------------------------------------------------- 1 | # JavaScript for less-capable browsers 2 | 3 | **Date:** 2018-05-16 4 | 5 | **Status:** Superseded by [006 - JavaScript browser compatibility](https://github.com/alphagov/govuk-design-system-architecture/blob/main/decision-records/006-javascript-compatibility.md) 6 | 7 | ## Note 8 | 9 | polyfill.io was reported as compromised on 25th June 2024 and we are no longer recommending it as a polyfilling service. Additionally, we have removed the polyfills we created with it from govuk-frontend v5+. 10 | 11 | ## Context 12 | 13 | Before GOV.UK Frontend, our projects used jQuery for DOM interactions, events and data manipulation. 14 | 15 | We’re taking a step back from jQuery due to its lack of support for the browsers we support, its large file size, lack of security updates and from conversations with the community. 16 | 17 | ## Decision 18 | 19 | We’re now writing standard ES5 JavaScript instead, that we polyfill where necessary. 20 | 21 | This means that in places where we would have previously used [`$.each`](http://api.jquery.com/jquery.each/) we’re using [`.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) instead, and polyfilling the missing gaps. 22 | 23 | We use polyfills provided by the Financial Times’ [Polyfill service](https://polyfill.io). 24 | 25 | This approach ensures that multiple polyfills can be sourced from this service with greater confidence that they’ll work without conflicting with each other. 26 | 27 | The Polyfill service does not do runtime detection in browsers and instead opts to do this on the server via user-agent sniffing. It only ships the code needed for that browser, which means newer browsers don’t have to run anything. We may investigate lazy-loading in the future, but for now we’re using a bundled approach based on the lowest common denominator. 28 | 29 | We are vendoring these polyfills to avoid any [single point of failure](https://en.wikipedia.org/wiki/Single_point_of_failure) issues that could arise from relying on a CDN. By doing this, we can detect if polyfills are needed at runtime, which results in all browsers getting the same polyfill bundle. 30 | 31 | We hope that our approach can be automated or moved into a reusable npm package, based on the Financial Times [npm package](https://github.com/Financial-Times/polyfill-service#library). 32 | 33 | Here is an [example of polyfilling `addEventListener`](https://github.com/alphagov/govuk-frontend/blob/master/docs/polyfilling.md). 34 | 35 | Any polyfills included in GOV.UK Frontend will be tested to work in supported browsers and devices, including assistive technology. Any community discussion and documentation around potential bugs or downsides will also be considered before deciding to include a polyfill in GOV.UK Frontend. 36 | 37 | ## Consequences 38 | 39 | ### Advantages 40 | 41 | - We’re not forcing projects to include and rely on a specific library 42 | - Developers don’t need to know or learn a specific library 43 | - The JavaScript code is standard and transferable 44 | - It’s very easy to remove the polyfills when older browser support is dropped while keeping the same JavaScript code 45 | - Approach can be easily maintained and used by the community 46 | - Polyfills are widely maintained by the industry 47 | 48 | ### Disadvantages 49 | 50 | - There are risks modifying globals or native object prototypes 51 | - https://www.w3.org/2001/tag/doc/polyfills/#always-encapsulate 52 | - http://perfectionkills.com/whats-wrong-with-extending-the-dom/ 53 | - We cannot be sure if our polyfills work with other third party code 54 | 55 | ## References 56 | 57 | - [Polyfills and the evolution of the Web](https://www.w3.org/2001/tag/doc/polyfills/) 58 | - [Polyfill approach discussion on GitHub](https://github.com/alphagov/govuk-frontend/issues/676) 59 | -------------------------------------------------------------------------------- /decision-records/002-restructure-based-on-single-package.md: -------------------------------------------------------------------------------- 1 | # Restructure single GOV.UK Frontend package 2 | 3 | **Date:** 2018-05-10 4 | 5 | **Status:** Accepted 6 | 7 | ## Context 8 | 9 | We implemented the [002 Proposal](https://github.com/alphagov/govuk-design-system-architecture/blob/master/proposals/002-publish-one-npm-package-instead-of-multiple-npm-packages.md) in https://github.com/alphagov/govuk-frontend/pull/680 10 | 11 | We have then restructured the code base in https://github.com/alphagov/govuk-frontend/pull/693 12 | 13 | This is to: 14 | 15 | - solve issues around components importing files that export CSS 16 | - take advantage of the single package - the old structure was based around each folder being it's own package. 17 | - make the entry points to files clearer. 18 | - better reflect conventions by giving each layer it's own folder, this moves them out of a confusingly named 'global' parent folder. 19 | 20 | ## Decision 21 | 22 | ### Structure 23 | 24 | GOV.UK Frontend is broken into a number of layers in order to help provide a 25 | logical structure, loosely following the conventions of [ITCSS]. 26 | 27 | 1. [Settings](#settings) 28 | 2. [Tools](#tools) 29 | 3. [Helpers](#helpers) 30 | 4. [Core](#core) 31 | 5. [Objects](#objects) 32 | 6. [Components](#components) 33 | 7. [Utilities](#utilities) 34 | 8. [Overrides](#overrides) 35 | 36 | Each folder has its own entry point (`_all.scss`). 37 | 38 | ### Settings 39 | 40 | Global variables for the project, for example colour palettes and spacing and 41 | typography scales. 42 | 43 | This layer should not output any CSS. 44 | 45 | ### Tools 46 | 47 | Mixins or functions that implement either logic (e.g. conditionally outputting 48 | CSS) or calculations, and that need to be made available globally. 49 | 50 | This layer should not output any CSS. 51 | 52 | ### Helpers 53 | 54 | Mixins that abstract common styling (for example, focus states or visually 55 | hidden content) 56 | 57 | This layer should not output any CSS. 58 | 59 | ### Core 60 | 61 | Basic content styles for typography, links etc. The classes defined in this 62 | layer would generally correspond to an HTML element - for example paragraphs, 63 | headings, lists or links. 64 | 65 | ### Objects 66 | 67 | Objects can range from something as simple as a wrapper element, to layout 68 | systems. 69 | 70 | They may be used in any number of unrelated contexts to the one you can 71 | currently see it in. This means that making modifications to these types of 72 | class could potentially have knock-on effects in other places. 73 | 74 | ### Components 75 | 76 | Discrete pieces of UI. In most cases these will map to the components in the 77 | Design System. 78 | 79 | ### Utilities 80 | 81 | Utility classes – for example clearing floats, visually hiding content. 82 | 83 | ### Overrides 84 | 85 | Classes that map to a specific property – for example margin or font weight - 86 | and override all other layers. Rules in this layer will generally be marked as 87 | !important. 88 | 89 | Class names within this layer use an additional prefix `-!-`, for example 90 | `.govuk-!-w-regular`. 91 | 92 | [ITCSS]: (http://www.creativebloq.com/web-design/manage-large-css-projects-itcss-101517528) 93 | 94 | ## Consequences 95 | 96 | The paths to import the project are changed, this has been detailed in the release notes for GOV.UK Frontend. 97 | -------------------------------------------------------------------------------- /decision-records/003-templating-languages.md: -------------------------------------------------------------------------------- 1 | # Templating languages 2 | 3 | **Date:** 2018-07-05 (Historical) 4 | 5 | **Status:** Accepted 6 | 7 | ## Context 8 | 9 | Before GOV.UK Frontend, you needed to use 3 different libraries to build a 10 | service that looked like GOV.UK: 11 | 12 | - GOV.UK Frontend Toolkit 13 | - GOV.UK Template 14 | - GOV.UK Elements 15 | 16 | GOV.UK Template provides the boilerplate, header, footer and related assets like 17 | the favicon, and is available in a number of different formats: 18 | 19 | - a gem containing a Rails engine 20 | - a tarball containing Play Framework templates 21 | - a folder containing Mustache templates 22 | - a tarball containing Liquid templates 23 | - a tarball containing Mustache Inheritance templates 24 | - a tarball containing Jinja templates 25 | - a tarball containing plain HTML and assets 26 | - a tarball containing Embedded JavaScript (EJS) templates 27 | - a JAR file containing assets but no templates, structured as per WebJars 28 | - a tarball containing Django templates 29 | 30 | Making GOV.UK Template available in a number of formats provides a convenient 31 | way for service teams across government to start a new GOV.UK project, despite 32 | the number of different tech-stacks being used. 33 | 34 | These different formats are automatically generated from a base ruby ERB 35 | template through the use of different '[compilers][template-compilers]', 36 | '[packagers][template-packagers]' and '[publishers][template-publishers]' for 37 | each target format. 38 | 39 | GOV.UK Elements, which contains the rest of the UI Elements that you would need 40 | to use, does not support any sort of templating language. The only thing that it 41 | provides is an [npm package containing the Sass][elements-sass]. It relies on 42 | users copying and pasting HTML from the examples in the online documentation. 43 | 44 | The way that the different formats in GOV.UK Template are generated is fairly 45 | simple. It supports the substitution of blocks and variables, but is unable to 46 | handle loops, complex logic or many of the other features provided by most 47 | templating languages. For this reason, we do not think that we could use the 48 | same technique to provide the components in GOV.UK Frontend in multiple formats. 49 | We investigated other ways of doing this in alpha, which are outlined below, but 50 | found that doing so in a reliable way would involve significant work. 51 | 52 | Overall we do not think that the pain points involved in maintaining a setup of 53 | this nature are worth the benefit if we are only able to provide the 'header, 54 | footer and boilerplate in multiple formats, given how rarely they change. The 55 | [HTML in GOV.UK Template has not changed very much][template-changes] in the 56 | years it has existed. 57 | 58 | 59 | ### Pain points 60 | 61 | - The team do not have working knowledge of a number of the target languages and 62 | frameworks. This would make it difficult to fix issues that might be reported, 63 | or to update the template to work with new versions of the different 64 | frameworks that might be released. 65 | 66 | - There are integration tests for some of the target languages and frameworks, 67 | but not all. This makes it difficult to make substantial changes to Template 68 | whilst being confident that those changes will work everywhere unless you do 69 | substantial manual testing. It would be possible to set up test harnesses for 70 | every target language and framework, but this would be significant work. 71 | 72 | - The build pipeline is reasonably complex with a number of downstream builds 73 | being kicked off in other repositories, making it hard to diagnose when issues 74 | arise. It also publishes to a number of different package managers using a 75 | variety of different methods. 76 | 77 | ### Transpiling templates 78 | 79 | [Transpilation][transpilation] is the act of taking source code written in one 80 | language and producing an equivalent version in another language. 81 | 82 | In [alpha][alpha] the team explored ways of doing this by using [shawnbot/meta- 83 | template][meta-template] which converts the source template into an [abstract 84 | syntax tree][ast] and uses that to generate the destination template. We created 85 | a [working example][alpha-transpilation] which involved [adding an ERB 86 | formatter][meta-template-pr] to meta-template. 87 | 88 | However, meta-template was in its infancy and not something we could adopt 89 | without doing significant work. It was also difficult to establish which 90 | templating language features, for example, default variables for variables, were 91 | going to be available in every templating language we wanted or might want to 92 | support, and therefore which features were safe to use in the source template. 93 | 94 | There is also the risk of making contribution more difficult, as contributors 95 | may discover issues with transpilation during development that they do not know 96 | how to solve. For example, tests may fail because they're using a new feature 97 | that either doesn't work in another templating language, or that the transpiler 98 | doesn't know how to transpile. 99 | 100 | 101 | ## References 102 | 103 | There's a [talk by Alice Bartlett from Patterns Day 2017][alice-talk] that 104 | touches on some of these challenges (the most relevant section starts at 105 | around 10 minutes in). 106 | 107 | 108 | ## Decision 109 | 110 | We will use a single templating language which will allow us to define the 111 | markup for a component in a single place. 112 | 113 | We will not build integrations into other languages or frameworks. Our 114 | 'deliverable' will be in the form of one or more npm packages containing the 115 | Sass and JavaScript. 116 | 117 | We may decide to look at transpilation again in the future, based on the 118 | feedback that we get from our users. 119 | 120 | ## Consequences 121 | 122 | We think there is still going to be a need for either libraries or example apps 123 | to help users integrate GOV.UK Frontend into their project, but we hope that 124 | they can: 125 | 126 | - be built and supported by teams and individuals within the community who have 127 | a good working knowledge of the framework or language in question. 128 | - be built in such a way that they do not vendor GOV.UK Frontend, so that they 129 | do not need to be updated every time GOV.UK Frontend is updated. 130 | 131 | 132 | [template-compilers]: https://github.com/alphagov/govuk_template/tree/master/build_tools/compiler 133 | [template-packagers]: https://github.com/alphagov/govuk_template/tree/master/build_tools/packager 134 | [template-publishers]: https://github.com/alphagov/govuk_template/tree/master/build_tools/publisher 135 | [elements-sass]: https://www.npmjs.com/package/govuk-elements-sass 136 | [template-changes]: https://github.com/alphagov/govuk_template/commits/master/source/views/layouts/govuk_template.html.erb 137 | [transpilation]: https://en.wikipedia.org/wiki/Source-to-source_compiler 138 | [ast]: https://en.wikipedia.org/wiki/Abstract_syntax_tree 139 | [meta-template]: https://github.com/shawnbot/meta-template 140 | [meta-template-pr]: https://github.com/shawnbot/meta-template/pull/6 141 | [alpha]: https://github.com/alphagov/govuk_frontend_alpha 142 | [alpha-transpilation]: https://github.com/alphagov/govuk_frontend_alpha/tree/master/lib/transpilation 143 | [alice-talk]: https://vimeo.com/226575101 144 | 145 | 146 | -------------------------------------------------------------------------------- /decision-records/004-new-version-font.md: -------------------------------------------------------------------------------- 1 | # New version of font 2 | 3 | **Date:** 2019-07-29 4 | 5 | **Status:** Accepted 6 | 7 | ## Context 8 | 9 | There were a [number of issues with "NTA"](https://github.com/alphagov/govuk-frontend/issues/1012), the previous version of the font: 10 | 11 | 1. The file size for all versions of the font was larger than it needed to be. 12 | 2. A separate font was required for tabular numbers. 13 | 3. The glyphs sat too high in the fonts bounding box (baseline) which led to the need for adjustments in CSS. 14 | 4. Hinting requirement for oldIE (EOT) increased the file size even further. 15 | 16 | ## Decision 17 | 18 | - Replace the "NTA" font with a new version, called "GDS Transport", which fixes the above issues. 19 | - Specifically, stop serving Transport font to IE8 due to a [large file required for hinting](https://designnotes.blog.gov.uk/2019/07/29/weve-updated-the-gov-uk-colours-and-font/). The font now [falls back to Arial](https://github.com/alphagov/govuk-frontend/blob/master/CHANGELOG.md#gds-transport-now-falls-back-to-arial-in-internet-explorer-8-ie8) for IE8. 20 | 21 | ## Consequences 22 | - Font files are now smaller: WOFF2 files are ~33kb and ~31kb, compared with ~66kb and ~54kb of the previous version of the font 🎉 23 | - The vertical alignment of the font has been corrected. This removes the need for manually adjusting the baseline of the font. 24 | - Tabular numbers are now part of the [`govuk-font` mixin](http://govuk-frontend-review.herokuapp.com/docs/#helpers-mixin-govuk-font), instead of a separate font family. 25 | - The previous version of the font is now deprecated. Service teams using the legacy code bases [can still use the previous version in compatibility mode](https://github.com/alphagov/govuk-frontend/blob/master/docs/installation/compatibility.md). 26 | 27 | ## Advantages 28 | 29 | - Improved page performance due to smaller font files. 30 | - No need to adjust the font baseline manually. This means simpler code and less design / development work. 31 | - With the baseline adjustments removed, the font can be swapped for a different one such as Arial without manually having to remove the baseline adjustments. An example would be if [the service is not on gov.uk](https://www.gov.uk/service-manual/design/making-your-service-look-like-govuk#if-your-service-isnt-on-govuk). 32 | - Simpler documentation for using tabular numbers which are now part of the `govuk-font` mixin. Using tabular numbers no longer requires loading in a separate font, leading to performance gains. 33 | - IE8 will not download the font files but falls back to a default font, leading to performance gains. 34 | 35 | ## Disadvantages 36 | 37 | - Service teams might need to make adjustments in their custom components which contain corrections to the baseline of the font. 38 | -------------------------------------------------------------------------------- /decision-records/005-repository-organisation-for-v5.md: -------------------------------------------------------------------------------- 1 | # Restructure govuk-frontend repository for v5 2 | 3 | **Date:** 2023-04-21 4 | 5 | **Status:** Accepted 6 | 7 | ## Decision 8 | 9 | 10 | 11 | To prepare the codebase for v5, we've agreed to make the following changes to the files in our repository and their location: 12 | 13 | 1. Create `govuk-frontend` and `govuk-frontend-review` packages 14 | - Create a `govuk-frontend` npm package. 15 | - Move source files (currently `src` ) and built package files (currently `package`) to this package. 16 | - Keep shipping only the built files to npm for now. We'll use the `files` field of `package.json` to include directories in the shipped package, and `.npmignore` to exclude specific files (like tests) 17 | - Create a `govuk-frontend-review` package for the review app 18 | - Store these in a `packages` folder 19 | 2. Create shared `config`, `lib`, `tasks` and `helpers` packages 20 | 3. Remove the built package files (currently `package`) from version control 21 | 4. Update our release process to make sure we keep checking the changes (possibly manually) between the package to be released and the previous version 22 | 5. Leave `dist` in its current location for now (we may revisit whether it's in version control or at the root in the future). These are compiled files for use without npm. 23 | 24 | This will yield the following structure for our repository: 25 | 26 | ``` 27 | govuk-frontend // Repository root 28 | ├── ... 29 | ├── dist // Built files for use without npm 30 | ├── packages // Parent folder for packages 31 | │ ├── govuk-frontend // The GOV.UK Frontend package 32 | │ │ ├── dist // [Previously `/package`] Generated build files, not in version control, ships to npm 33 | │ │ ├── src // [Previously `/src`] Source files, in version control, not shipped to npm 34 | │ │ ├── tasks // Build, release and Gulp tasks for the GOV.UK Frontend Package 35 | │ │ ├── package.json // Ensures dependencies of src, dist and tasks are in-sync 36 | │ │ └── ... 37 | │ ├── govuk-frontend-review // The Review App package 38 | │ │ ├── dist // Not in version control. Some tasks need the review app to build (tests, for example) 39 | │ │ ├── src // [Previously `app/src`] Source files for review app 40 | │ │ ├── tasks // Build and watch tasks for the review app 41 | │ │ ├── package.json 42 | │ │ └── ... 43 | ├── shared // Parent folder for packages shared across the monorepo 44 | │ ├── config // [Previously `/config`] Stores config info like filepaths and ports 45 | │ ├── helpers // Helper functions for development 46 | │ ├── lib // [Previously `/lib`] Shared libraries 47 | │ └── tasks // [Previously `/tasks`] Shared tasks 48 | ├── src // Contains symlinks to new source file locations 49 | └── package.json // Workspaces configuration and top-level dependencies 50 | ``` 51 | 52 | ## Rationale 53 | 54 | 55 | 56 | ### Creating `govuk-frontend` and `govuk-frontend-review` packages 57 | 58 | #### **Overview** 59 | These are the packages we "ship" in some form (we publish `govuk-frontend` to npm, and we deploy `govuk-frontend-review` to Heroku), so it makes sense to group them, and the `packages` folder is a convention seen across other repos. This also allows us to better organise our dependencies between the two. 60 | 61 | #### **`govuk-frontend`** 62 | We may need to ship with dependencies in the future. For example: 63 | 64 | - peer dependencies to a polyfill library if we shipped a version compiled with `import` statements for the polyfills (rather than having the polyfills bundled in) 65 | - dependencies to other libraries, if we were shipping a Babel preset or PostCSS configuration 66 | 67 | Moving the source and built files within the same package helps us ensure these dependencies are resolved consistently. 68 | 69 | While we don't yet have any dependencies, moving these files changes the shape of our package, requiring users to update their import paths for Nunjucks, making it a breaking change. Taking advantage of the breaking nature of the v5 release sets us up so we don't have to worry about future dependencies. 70 | 71 | This doesn't force us to ship the source files, which we've decided to exclude (at least for now). We can choose which folders to include via the `files` field in `package.json`, and use `.npmignore` to exclude specific files. 72 | 73 | #### **`govuk-frontend-review`** 74 | The review app uses relative paths (`../../src/...`) to access the components of GOV.UK Frontend. While we cannot make it consume `govuk-frontend` the exact same way our users do (downloading from an `npm` registry), we can get pretty close using workspaces. Making it use `govuk-frontend` directly helps ensure that: 75 | - we're consuming the built files, not rebuilding from source with a process that we have to keep in sync with how the `govuk-frontend` package is built 76 | - the actual files work as intended 77 | - `entries` in `package.json` are properly configured 78 | - dependencies get resolved as expected (we'll still need a different route to test `peerDependency` if we introduce them, though) 79 | 80 | ### Creating config, helpers, lib and tasks packages 81 | 82 | These are all internal tooling packages which we don't ship, which are used across our shipped packages. Grouping them in a `shared` folder is a convenience; the main benefit of splitting them this way is dependency organisation. 83 | 84 | ### Removing built package files from version control 85 | 86 | Since we will be consuming `govuk-frontend` from the `govuk-frontend-review` app, we need to rebuild the `govuk-frontend` package regularly, rather than only at the point of release. 87 | 88 | If we were to leave these built files in version control, we'd risk committing built files that are somewhere between the previous release and the next one. Removing them ensures we can rebuild at will. 89 | 90 | ### Updating our release process 91 | 92 | Including the built files in version control serves as a way to check that there's no weird code sneaking in. Changes to the package get highlighted during the review of the pull request raised to commit the new build of the package and the release. 93 | 94 | We'll need to keep checking for unexplained changes to the package as we release, even if it is by manually diffing for a while (before further automation). 95 | 96 | ### Leaving `dist` in its current location 97 | 98 | `dist` doesn't need to move to enable the previous points, and with the amount of changes in v5, we'll leave it out of the equation for now. 99 | 100 | ## Risks and constraints 101 | 102 | 103 | 104 | - There may be some named-based confusion. 105 | - We previously used `package` as folder to build into, rather than manually edit files. Now, the `packages` folder contains sources. 106 | - Similarly, we'll have a `dist` folder at root, as well as in each package's folder. This will be mitigated somewhat by removing the non-root `dist` folders from version control, but we might want to consider renaming the root `dist` folder to something like `release`. 107 | - External contributors may be used to the current structure of the repository and confused by the relocation. We will help with this by leaving hints in README files and symlinks to the new locations. 108 | 109 | ## Alternatives considered 110 | 111 | 112 | 113 | ### Creating `govuk-frontend` and `govuk-frontend-review` packages 114 | 115 | - Keeping the review app in the `app` folder and repurposing the `package` folder for the `govuk-frontend` package 116 | - This would create some naming confusion since we previously used `package` for automatically built code 117 | - We'd be splitting packages across the base directory, `shared` and `package`, which might be a bit confusing 118 | - Holding off on `govuk-frontend` source files and built package files within the same package 119 | - This would mean waiting for the next breaking change to do it. We may need to have peer dependencies before that release 120 | 121 | ### Creating config, helpers, lib and tasks packages 122 | 123 | - Moving the `shared` folder into the `packages` folder 124 | - The location of the shared folder was kept to root to distinguish it from the "shipped" packages in the `packages` folder 125 | 126 | ### Removing built package files from version control 127 | 128 | - We could also have built the package to a separate folder that's not in version control (for ex. `govuk-frontend-local-build`) to ensure we consume the built files without impacting `package`. We'd have to duplicate efforts to maintain two `package.json` files and lose testing our dependency resolution, package exports and complicate the linting and Dependabot updates. 129 | - Each PR could get a package deployed to the [Github npm registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry) allowing its installation by the review app down the line. This requires extra infrastructure though, and doesn't help when running locally. 130 | 131 | ## Implications 132 | 133 | 134 | 135 | - Users will need to update their import paths when migrating to v5, which we can document as part of the release notes/migration docs. 136 | - Ongoing new components (Exit This Page, Tasklist) will need to have their sources relocated before they can be merged in the new code structure. We can help with moving things and can release Exit This Page from a support branch if it needs to go before v5. 137 | - We need to keep making sure our configuration for the GOV.UK Prototype Kit gets recognised by the Kit and picks up our files as necessary. 138 | 139 | ## Contributors 140 | 141 | 142 | - Brett Kyle (@domoscargin) 143 | - Colin Rotherham (@colinrotherham) 144 | - Oliver Byford (@36degrees) 145 | - Romaric Pascal (@romaricpascal) 146 | 147 | ## Associated issues and pull requests (PRs) 148 | 149 | 150 | - https://github.com/alphagov/govuk-frontend/issues/3291 151 | - https://github.com/alphagov/govuk-frontend/issues/2886 152 | - https://github.com/alphagov/govuk-frontend/issues/3547 153 | - https://github.com/alphagov/govuk-frontend/issues/3548 154 | - https://github.com/alphagov/govuk-frontend/pull/3498 155 | 156 | 157 | ## Outcomes 158 | 159 | 160 | 161 | Part of the discussion around this decision clarified that the review `app` does not need to take responsibility for all development processes. Performance monitoring, for example, can happily happen in its own workspace and feed the app something to serve if necessary. Same could go for testing that the different compiled versions work appropriately if/when we start shipping more than one variant of compiled files. 162 | 163 | It was also mentioned, discussing the possibility of dependencies, that we'll need to be mindful of the implications of the dependencies we add (provenance, maintenance...). 164 | -------------------------------------------------------------------------------- /decision-records/006-javascript-compatibility.md: -------------------------------------------------------------------------------- 1 | # JavaScript browser compatibility 2 | 3 | Date: 27/06/23 4 | 5 | Status: Accepted 6 | 7 | ## Decision 8 | 9 | We will publish JavaScript that can be parsed without errors in browsers supporting `