Change source files to build artefacts mapping

[alexander-entin]

What is the current behaviour?
Currently, source files map to build artefacts as following:

1. src/template.html -> /index.html
2. src/manifest.json -> /manifest.json
3. src/.(js|css) -> /bundleZZZ.
4. src/assets/** -> /assets/
5. src/assets/favicon.ico -> /favicon.ico (in addition to /assets)
6. src/static/** -> / (ex. robots.txt)

What is the motivation or use case for changing this behaviour?
'assets' was created by 'simple' template. OK.
Then I found I need 'static' for robots.txt. #436.
Then I found I need regexes for caching rules. #1364.
Now, when adding/looking for an asset I have to recollect the difference between 'assets' and 'static'. #1611
If I try to simplify and use 'static' instead of 'assets', favicon link is not added to the html.
If I put manifest.json to 'static', title is not expanded properly in the html.
Even if I fix favicon and title in the html manually, 'assets' is still required (with at least one file).
So, we need to use all 'assets' and 'static' and '/' and remember what goes where.

Describe the solution you'd like
Can these 6 rules be simplified to 2?

1. public/** -> / (including index.html, manifest.json, favicon.ico, robots.txt)
2. src/.(js|css) -> /static/bundleZZZ. (to be able to cache the whole 'static' folder agressively)

Please mention any other relevant information.
This is how create-react-app does it.
As a lot of devs come from there, it could be beneficial to match.

Above points are rather minor, and could possibly be resolved by re-configuration.
But absence of good defaults kills otherwise "streamlined" feeling.
Especially after using create-react-app where it all "just works".

Please paste the results of npx preact-cli info here.
System:
OS: Windows 10 10.0.19043
CPU: (8) x64 Intel(R) Core(TM) i5-8250U CPU @ 1.60GHz
Binaries:
Node: 16.13.2 - C:\Program Files\nodejs\node.EXE
Yarn: 1.22.15 - C:\Program Files\nodejs\yarn.CMD
npm: 7.19.0 - C:\Program Files\nodejs\npm.CMD
Browsers:
Chrome: 99.0.4844.51
Edge: Spartan (44.19041.1266.0), Chromium (99.0.1150.36)
npmPackages:
preact: ^10.1.0 => 10.6.6
preact-cli: ^3.0.0 => 3.3.5
preact-render-to-string: ^5.1.2 => 5.1.20

[rschristian]

Really the only rules are src/assets -> build/assets, src/static -> build/, src/manifest -> build/manifest.

The template.html -> index.html (or as many routes as you prerender) exists to emphasize that this is not a standard HTML file; it's actually EJS and you can do all sorts of templating in it, which is something we certainly encourage where appropriate. So the difference in name (as you'll always have an index.html) is entirely intentional to ensure users don't think it's a straight copy from src to build.

If I try to simplify and use 'static' instead of 'assets', favicon link is not added to the html.

We need to pass the favicon path to html-webpack-plugin in order for it to be consumed. If you move the file around, we will have no way of knowing where it is or what it's called. At that point it's your job to use your preact.config.js to pass the correct file path to html-webpack-plugin.

The output favicon file (/favicon.ico) is generated by html-webpack-plugin. We don't make an additional copy.

If I put manifest.json to 'static', title is not expanded properly in the html.

That's just 2 of the 6 fallback values. You can specify titles for pages through your prerender data, or, if you just have the single page, you can write it in your template.

Lot of flexibility there, and I'd argue you probably don't want to connect your HTML title to your manifest, in all honesty.

src/.(js|css) -> /static/bundleZZZ. (to be able to cache the whole 'static' folder agressively)

You're in control of the output, you have the entire Webpack config available to you. Some users disable hashed filenames, at which point static/ fails to make much sense. Some users cache every file. Really, it depends.

Again, unlike CRA, you have the full freedom to edit as you see fit. Outputting everything to build/ is pretty un-opinionated and should appeal to a wide audience.

Especially after using create-react-app where it all "just works".

That's a bit odd, as the exact same problems exist in CRA: blindly move files around and you won't get the desired output. At least here you can configure the build process as you'd like using your preact.config.js.

I don't know if we're interested in a public dir, I kind of dislike that pattern, but I do agree, it certainly could do with some improvement. I think any real change here would be breaking though, so will have to wait for a v4.

[benedictjohannes]

@rschristian if those rules are documented (at least in this repo's README), I'd say the rules are excellent and totally workable. I like this rules more than the public pattern.

Do you plan to add this to the documentation? Ideally the Preact's website should also be updated to document this.

I encountered the @mui/material example still using create-react-app with react-app-rewired, which is at least not ideal in the presence of preact-cli. I am working on porting this example to preact-cli, but had difficulties in finding where to place the "public" contents like assets. It's only through your comment that I know where to start, which is probably not ideal.

[rschristian]

Do you plan to add this to the documentation?

I have #1611 to track this, though my list of things to do is exceptionally long at the moment. It'd probably go into the wiki rather than the ReadMe, as that's already getting to the point where it's difficult to navigate around it.

Ideally the Preact's website should also be updated to document this.

We don't really document preact-cli on the Preact site anymore. There hasn't really been any meaningful change there in years. Not really sure what to do about that, but our docs are effectively here in the readme & on the wiki.

Maybe I could write up a new docs site like what we've done to document WMR, but that'd need an even greater time investment from me (or anyone else looking to do it).

I encountered the @mui/material example still using create-react-app with react-app-rewired, which is at least not ideal in the presence of preact-cli

I wouldn't really say that. We have a couple first-party (preact-cli & wmr) and recommended third-party (vite) build tools. Use whatever you fancy, really. Nothing wrong with a CRA example, especially for something like a component library.

It's only through your comment that I know where to start, which is probably not ideal.

Totally agree. Contributions always welcome of course. The copy patterns are here:

preact-cli/packages/cli/lib/lib/webpack/webpack-client-config.js

Lines 82 to 96 in fcd0375

	let copyPatterns = [
	existsSync(source('manifest.json')) && { from: 'manifest.json' },
	// copy any static files
	existsSync(source('assets')) && { from: 'assets', to: 'assets' },
	// copy sw-debug
	!env.isProd && {
	from: resolve(__dirname, '../../resources/sw-debug.js'),
	to: 'sw-debug.js',
	},
	// copy files from static to build directory
	existsSync(source('static')) && {
	from: resolve(source('static')),
	to: '.',
	},
	].filter(Boolean);