Update stylesheet and javascript folder names/paths in template repository

[frankieroberto]

For users following the Updating the kit guidance or via the GitHub 'Use this template' button, they now see built CSS served from /css /assets/sass because NHS.UK prototype kit v8 preserves the input/output directories

We could bring these into line with the convention for NHS.UK frontend?

May need to update guidance too.

Before in v7

Other than images, output directories could not be determined easily:

Source	Destination	URL path
app/assets/images	public/images	/images
app/assets/sass	public/css	/css
app/assets/javascript	public/js	/js

After in v8

Output directories can now be determined easily but /assets/sass is unexpected for built CSS:

Source	Destination	URL path
app/assets/images	Not built (routed from source)	/assets/images
app/assets/sass	public/assets/sass	/assets/sass
app/assets/javascript	public/assets/javascript	/assets/javascript

Note: Images and other assets are automatically routed from source without a build step

• public/* → URL path /*
• app/assets/* → URL path /assets/*
• app/images/* → URL path /images/*

e.g. Making a request for /assets/manifest.json will try these files on disk, in order:

1. public/assets/manifest.json
2. app/assets/manifest.json

Custom entryPoints

Although using buildOptions.entryPoints you can actually set these up however you prefer:

Source	Destination	URL path
app/assets/images	Not built (routed from source)	/assets/images
app/stylesheets	public/stylesheets	/stylesheets
app/javascripts	public/javascripts	/javascripts

[frankieroberto]

Any thoughts on what the default folder names should be?

The NHS digital service manual, NHS.UK frontend review app, GOV.UK Design system, GOV.UK Frontend review app, GOV.UK Frontend docs and the MOJ Design System use assets, stylesheets and javascripts

├─┬ assets
│ └── images
├── stylesheets
└── javascripts

Which appears to come from The GDS Way which uses assets images instead:

├── images
├── stylesheets
└── javascripts

Similarly the GOVUK Prototype kit uses stylesheets and javascripts but prefixed with /public:

└─┬ public
  ├── stylesheets
  └── javascripts

Whereas the NHS Design history for NHS.UK services template uses styles, and doesn’t have a javascripts folder.

🤷

[edwardhorsford]

I'd probably propose css or styles over sass. It's doubly weird as the internal types are likely sass/scss but what's rendered is css - so sass appearing in the output path feels wrong.

[joelanman]

it's not super clear what this issue is referring to, but its important to note assets and public are different concepts.

assets - the original files, as used during development. Examples would be sass, or unprocessed source files
public - the files served to the browser, often processed in some way (sass > css, compressed js and images, for example)

[frankieroberto]

@joelanman so in the NHS prototype kit, app/assets is currently served using Express static, and then app/assets/sass and app/assets/javascript are currently built using esbuild and output into app/public/assets/sass and app/public/assets/javascript - and app/public is also served using Express static.

This behaviour is semi-configurable, as you can specify a list of entryPoint folders in your app.js, which will all be processed by esbuild into public - see https://github.com/nhsuk/nhsuk-prototype-kit/blob/main/app.js#L14-L17

So technically at the moment, your unprocessed sass will be served at http://localhost:3000/assets/sass/main.scss and your processed sass at http://localhost:3000/assets/sass/main.css. Which is a bit of a weird side-effect of the css being in a subfolder of assets, but doesn't do much harm.

We could change this though!

[colinrotherham]

@joelanman @frankieroberto I've updated the issue description

[joelanman]

Generally backwards compatibility is helpful unless you're trying to fix a problem

I'm a bit confused, the issue description says

Before in v7

app/assets/images → URL path /images

but the docs refers to a public folder, the same as the gov.uk kit

https://prototype-kit.service-manual.nhs.uk/guides/adding-assets/

[frankieroberto]

@joelanman ahh good point - docs are wrong! We no longer copy images and other assets from app/assets into public. Will update!

(serving them directly from app/assets is simpler and faster - although most prototypes probably don't have a ton of images)

[joelanman]

so.. you process the sass files into css files in the same folder? If so don't people sometimes edit the wrong one and lose their work when it gets overwritten?

[frankieroberto]

@joelanman it's a different folder. Source: app/assets/sass/main.scss, Destination: app/public/sass/main.css.

[colinrotherham]

I've updated the issue description again to include the source, destination and URL path

Sorry the automatic routing from source wasn't clear

[joelanman]

no worries :) then this might be a good approach

Source	Destination	URL path
app/assets/images	Not built (routed from source)	/assets/images
app/assets/sass	public/assets/css	/assets/css
app/assets/javascript	public/assets/javascript	/assets/javascript

[frankieroberto]

@joelanman I don’t mind that approach, except that we currently mirror the source and destination folder names (partly for flexibility as they're configurable, and partly for consistency), so it’d be:

Source	Destination	URL path
app/assets/images	Not built (routed from source)	/assets/images
app/assets/css	public/assets/css	/assets/css
app/assets/javascript	public/assets/javascript	/assets/javascript

(could also be named styles or js)

[colinrotherham]

Yeah, we're using esbuild entryNames: '[dir]/[name]' to make sure subdirectories are determined easily

My preferred approach would be to follow the NHS digital service manual and all our page template examples

├─┬ app
│ ├─┬ assets
│ │ └── images
│ ├── stylesheets
│ └── javascripts
│
└─┬ public
  ├── stylesheets
  └── javascripts

It's quite popular amongst both GOV and NHS with these examples from above:

The NHS digital service manual, NHS.UK frontend review app, GOV.UK Design system, GOV.UK Frontend review app, GOV.UK Frontend docs and the MOJ Design System use assets, stylesheets and javascripts