refactor: Move EJS into user templates (template.html) (#1768)

* refactor: Merging EJS templates and switcing preferred template extension to .ejs

* test: Fixing test suite to reflect latest changes

* chore: Cleaning

* docs: Updating ReadMe

* docs: Adding changeset

* refactor: Add error message for <% preact.(head|body)End %>

.changeset/hungry-peas-look.md

@@ -0,0 +1,9 @@
+---
+'preact-cli': major
+---
+
+To increase transparency and user control over the `template.html`, `<% preact.headEnd %>` and `<% preact.bodyEnd %>` will no longer be supported; instead, users should directly adopt the EJS and keep it in their templates.
+
+In the past, these were abstracted away as they were a bit unwieldy; EJS might be unfamiliar with users and the way data was retrieved from `html-webpack-plugin` was somewhat less than elegant. However, this has much improved over the years and the abstraction only makes simple edits less than obvious, so it is no longer fulfilling it's purpose.
+
+New projects will have a `template.ejs` created in place of the old `template.html`, containing the full EJS template. For existing projects, you can copy [the default `template.ejs`](https://github.com/preactjs/preact-cli/blob/master/packages/cli/src/resources/template.ejs) into your project or adapt it as you wish.

.eslintrc

@@ -1,19 +1,12 @@
 {
-  "extends": [
-    "eslint:recommended",
-    "prettier"
-  ],
+  "extends": ["eslint:recommended", "prettier"],
   "parser": "babel-eslint",
   "env": {
     "browser": true,
     "node": true,
     "es6": true
   },
-  "plugins": [
-    "babel",
-    "react",
-    "prettier"
-  ],
+  "plugins": ["babel", "react", "prettier"],
   "settings": {
     "react": {
       "pragma": "h",
@@ -29,6 +22,13 @@
   "rules": {
     "no-console": 1,
     "no-empty": 0,
+    "no-unused-vars": [
+      2,
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_"
+      }
+    ],
     "semi": 2,
     "keyword-spacing": 2,
     "require-atomic-updates": 0,

README.md

@@ -133,7 +133,7 @@ $ [npm run / yarn] preact build
     --babelConfig      Path to custom Babel config (default .babelrc)
     --prerender        Renders route(s) into generated static HTML  (default true)
     --prerenderUrls    Path to pre-rendered routes config  (default prerender-urls.json)
-    --template         Path to custom HTML template (default 'src/template.html')
+    --template         Path to custom EJS or HTML template  (default 'src/template.ejs')
     --inlineCss        Adds critical css to the prerendered markup  (default true)
     --analyze          Launch interactive Analyzer to inspect production bundle(s) (default false)
     -c, --config       Path to custom CLI config  (default preact.config.js)
@@ -159,7 +159,7 @@ $ [npm run / yarn] preact watch
     --cacert           Path to optional CA certificate override
     --prerender        Pre-render static content on first run
     --prerenderUrls    Path to pre-rendered routes config  (default prerender-urls.json)
-    --template         Path to custom HTML template (default 'src/template.html')
+    --template         Path to custom EJS or HTML template  (default 'src/template.ejs')
     --refresh          Enables experimental preact-refresh functionality
     -c, --config       Path to custom CLI config  (default preact.config.js)
     -H, --host         Set server hostname  (default 0.0.0.0)
@@ -219,7 +219,7 @@ To customize Babel, you have two options:
 
 #### Webpack
 
-To customize preact-cli create a `preact.config.js` or a `preact.config.json` file.
+To customize Preact-CLI's Webpack config, create a `preact.config.js` or a `preact.config.json` file:
 
 > `preact.config.js`
 
@@ -303,18 +303,15 @@ export default () => {
 
 #### Template
 
-A template is used to render your page by [EJS](https://ejs.co/).
-You can uses the data of `prerenderUrls` which does not have `title`, using `htmlWebpackPlugin.options.CLI_DATA.preRenderData` in EJS.
+To customize the HTML document that your app uses, edit the `template.ejs` file in your app's source directory.
 
-The default one is visible [here](packages/cli/src/resources/template.html) and it's going to be enough for the majority of cases.
+[EJS](https://ejs.dev) is a simple templating language that lets you generate HTML markup with plain JavaScript. Alongside `html-webpack-plugin`, you're able to conditionally add HTML, access your bundles and assets, and link to external content if you wish. The default we provide on project initialization should fit the majority of use cases very well, but feel free to customize!
 
-If you want to customise your template you can pass a custom template with the `--template` flag.
-
-The `--template` flag is available on the `build` and `watch` commands.
+You can customize the location of your template with the `--template` flag on the `build` and `watch` commands:
 
 ```sh
-preact build --template src/template.html
-preact watch --template src/template.html
+preact build --template renamed-src/template.ejs
+preact watch --template template.ejs
 ```
 
 ### Using CSS preprocessors

packages/cli/src/index.js

@@ -29,7 +29,7 @@ prog
 	.option('--babelConfig', 'Path to custom Babel config', '.babelrc')
 	.option(
 		'--template',
-		'Path to custom HTML template  (default src/template.html)'
+		'Path to custom EJS or HTML template  (default src/template.ejs)'
 	)
 	.option(
 		'--analyze',

packages/cli/src/lib/webpack/render-html-plugin.js

@@ -1,58 +1,107 @@
+const { mkdtemp, readFile, writeFile } = require('fs/promises');
+const { existsSync } = require('fs');
 const { resolve, join } = require('path');
 const os = require('os');
-const { existsSync, mkdtempSync, readFileSync, writeFileSync } = require('fs');
 const { Compilation, sources } = require('webpack');
 const {
 	HtmlWebpackSkipAssetsPlugin,
 } = require('html-webpack-skip-assets-plugin');
 const HtmlWebpackPlugin = require('html-webpack-plugin');
 const prerender = require('./prerender');
-const { error, esmImport, tryResolveConfig, warn } = require('../../util');
+const { error, esmImport, tryResolveConfig } = require('../../util');
 
 const PREACT_FALLBACK_URL = '/200.html';
 
-let defaultTemplate = resolve(__dirname, '../../resources/template.html');
-
-function read(path) {
-	return readFileSync(resolve(__dirname, path), 'utf-8');
-}
-
 /**
  * @param {import('../../../types').Env} env
  */
 module.exports = async function renderHTMLPlugin(config, env) {
 	const { cwd, dest, src } = config;
 
-	const inProjectTemplatePath = resolve(src, 'template.html');
-	let template = defaultTemplate;
-	if (existsSync(inProjectTemplatePath)) {
-		template = inProjectTemplatePath;
+	let templatePath;
+	if (config.template) {
+		templatePath = tryResolveConfig(
+			cwd,
+			config.template,
+			false,
+			config.verbose
+		);
 	}
 
-	if (config.template) {
-		const templatePathFromArg = resolve(cwd, config.template);
-		if (existsSync(templatePathFromArg)) template = templatePathFromArg;
-		else {
-			warn(`Template not found at ${templatePathFromArg}`);
+	if (!templatePath) {
+		templatePath = tryResolveConfig(
+			cwd,
+			resolve(src, 'template.ejs'),
+			true,
+			config.verbose
+		);
+
+		// Additionally checks for <src-dir>/template.html for
+		// back-compat with v3
+		if (!templatePath) {
+			templatePath = tryResolveConfig(
+				cwd,
+				resolve(src, 'template.html'),
+				true,
+				config.verbose
+			);
 		}
+
+		if (!templatePath)
+			templatePath = resolve(__dirname, '../../resources/template.ejs');
 	}
 
-	let content = read(template);
-	if (/preact\.(title|headEnd|bodyEnd)/.test(content)) {
-		const headEnd = read('../../resources/head-end.ejs');
-		const bodyEnd = read('../../resources/body-end.ejs');
-		content = content
-			.replace(/<%[=]?\s+preact\.title\s+%>/, '<%= cli.title %>')
-			.replace(/<%\s+preact\.headEnd\s+%>/, headEnd)
-			.replace(/<%\s+preact\.bodyEnd\s+%>/, bodyEnd);
+	let templateContent = await readFile(templatePath, 'utf-8');
+	if (/preact\.(?:headEnd|bodyEnd)/.test(templateContent)) {
+		const message = `
+			'<% preact.headEnd %>' and '<% preact.bodyEnd %>' are no longer supported in CLI v4!
+			You can copy the new default 'template.ejs' from the following link or adapt your existing:
+
+			https://github.com/preactjs/preact-cli/blob/master/packages/cli/src/resources/template.ejs
+		`;
+
+		error(message.trim().replace(/^\t+/gm, '') + '\n');
+	}
+	if (/preact\.title/.test(templateContent)) {
+		templateContent = templateContent.replace(
+			/<%[=]?\s+preact\.title\s+%>/,
+			'<%= cli.title %>'
+		);
 
 		// Unfortunately html-webpack-plugin expects a true file,
 		// so we'll create a temporary one.
-		const tmpDir = mkdtempSync(join(os.tmpdir(), 'preact-cli-'));
-		template = resolve(tmpDir, 'template.tmp.ejs');
-		writeFileSync(template, content);
+		const tmpDir = await mkdtemp(join(os.tmpdir(), 'preact-cli-'));
+		templatePath = resolve(tmpDir, 'template.tmp.ejs');
+		await writeFile(templatePath, templateContent);
 	}
 
+	let entrypoints = {};
+	const getEntrypoints = (compilation, publicPath) => {
+		// Retrieves the main bundle & dom-polyfills only, as they're
+		// the only defined entrypoints in the compilation
+		compilation.entrypoints.forEach((entrypoint, name) => {
+			let entryFiles = entrypoint.getFiles();
+
+			entrypoints[name] =
+				publicPath + entryFiles.find(file => /\.m?js(?:\?|$)/.test(file));
+		});
+
+		const optimizePlugin = compilation.options.plugins.find(
+			plugin => plugin.constructor.name == 'OptimizePlugin'
+		);
+		if (optimizePlugin) {
+			// Retrieves the (generated) legacy bundle
+			const legacyBundle = entrypoints['bundle']
+				.replace(publicPath, '')
+				.replace(/\.js$/, '.legacy.js');
+			entrypoints['legacy-bundle'] = publicPath + legacyBundle;
+
+			// Retrieves the (generated) es-polyfills
+			entrypoints['es-polyfills'] =
+				publicPath + optimizePlugin.options.polyfillsFilename;
+		}
+	};
+
 	const htmlWebpackConfig = values => {
 		let { url, title, ...routeData } = values;
 
@@ -72,23 +121,24 @@ module.exports = async function renderHTMLPlugin(config, env) {
 		return {
 			title,
 			filename,
-			template: `!!${require.resolve('ejs-loader')}?esModule=false!${template}`,
+			template: `!!${require.resolve(
+				'ejs-loader'
+			)}?esModule=false!${templatePath}`,
 			templateParameters: async (compilation, assets, assetTags, options) => {
-				let entrypoints = {};
-				compilation.entrypoints.forEach((entrypoint, name) => {
-					let entryFiles = entrypoint.getFiles();
-					entrypoints[name] =
-						assets.publicPath +
-						entryFiles.find(file => /\.(m?js)(\?|$)/.test(file));
-				});
+				// entrypoints are consistent across pages, so only extract once
+				if (!Object.keys(entrypoints).length) {
+					getEntrypoints(compilation, assets.publicPath);
+				}
 
 				return {
 					cli: {
 						title,
 						url,
 						manifest: config.manifest,
-						inlineCss: config['inlineCss'],
-						config,
+						// pkg isn't likely to be useful and manifest is already made available
+						config: (({ pkg: _pkg, manifest: _manifest, ...rest }) => rest)(
+							config
+						),
 						env,
 						prerenderData: values,
 						CLI_DATA: { prerenderData: { url, ...routeData } },
@@ -196,7 +246,7 @@ class PrerenderDataExtractPlugin {
 						}
 						let path = this.location_ + 'preact_prerender_data.json';
 						if (path.startsWith('/')) {
-							path = path.substr(1);
+							path = path.substring(1);
 						}
 						compilation.emitAsset(path, new sources.RawSource(this.data_));
 					}
@@ -205,5 +255,3 @@ class PrerenderDataExtractPlugin {
 		);
 	}
 }
-
-exports.PREACT_FALLBACK_URL = PREACT_FALLBACK_URL;

packages/cli/src/resources/template.ejs

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<title><% preact.title %></title>
+		<meta name="viewport" content="width=device-width,initial-scale=1">
+		<meta name="mobile-web-app-capable" content="yes">
+		<meta name="apple-mobile-web-app-capable" content="yes">
+		<link rel="apple-touch-icon" href="<%= htmlWebpackPlugin.files.publicPath %>assets/icons/apple-touch-icon.png">
+		<link rel="manifest" href="<%= htmlWebpackPlugin.files.publicPath %>manifest.json">
+		<% if (cli.manifest.theme_color) { %>
+			<meta name="theme-color" content="<%= cli.manifest.theme_color %>">
+		<% } %>
+	</head>
+	<body>
+		<%= cli.ssr %>
+		<% if (cli.config.prerender === true) { %>
+			<script type="__PREACT_CLI_DATA__">
+				<%= encodeURI(JSON.stringify(cli.CLI_DATA)) %>
+			</script>
+		<% } %>
+		<script type="module" src="<%= cli.entrypoints['bundle'] %>"></script>
+		<script nomodule src="<%= cli.entrypoints['dom-polyfills'] %>"></script>
+		<script nomodule src="<%= cli.entrypoints['es-polyfills'] %>"></script>
+		<script nomodule defer src="<%= cli.entrypoints['legacy-bundle'] %>"></script>
+	</body>
+</html>