docs: backend integration clarify tags to include in production HTML (#…

…16086)

docs/guide/backend-integration.md

@@ -66,7 +66,8 @@ If you need a custom integration, you can follow the steps in this guide to conf
        "isEntry": true,
        "dynamicImports": ["views/foo.js"],
        "css": ["assets/main.b82dbe22.css"],
-       "assets": ["assets/asset.0ab0f9cd.png"]
+       "assets": ["assets/asset.0ab0f9cd.png"],
+       "imports": ["_shared.83069a53.js"]
      },
      "views/foo.js": {
        "file": "assets/foo.869aea0d.js",
@@ -75,7 +76,8 @@ If you need a custom integration, you can follow the steps in this guide to conf
        "imports": ["_shared.83069a53.js"]
      },
      "_shared.83069a53.js": {
-       "file": "assets/shared.83069a53.js"
+       "file": "assets/shared.83069a53.js",
+       "css": ["assets/shared.a834bfc3.css"]
      }
    }
    ```
@@ -85,10 +87,54 @@ If you need a custom integration, you can follow the steps in this guide to conf
    - For non entry chunks, the key is the base name of the generated file prefixed with `_`.
    - Chunks will contain information on its static and dynamic imports (both are keys that map to the corresponding chunk in the manifest), and also its corresponding CSS and asset files (if any).
 
-   You can use this file to render links or preload directives with hashed filenames (note: the syntax here is for explanation only, substitute with your server templating language):
+4. You can use this file to render links or preload directives with hashed filenames.
+
+   Here is an example HTML template to render the proper links. The syntax here is for
+   explanation only, substitute with your server templating language. The `importedChunks`
+   function is for illustration and isn't provided by Vite.
 
    ```html
    <!-- if production -->
-   <link rel="stylesheet" href="/assets/{{ manifest['main.js'].css }}" />
-   <script type="module" src="/assets/{{ manifest['main.js'].file }}"></script>
+
+   <!-- for cssFile of manifest[name].css -->
+   <link rel="stylesheet" href="/{{ cssFile }}" />
+
+   <!-- for chunk of importedChunks(manifest, name)) -->
+   <!-- for cssFile of chunk.css -->
+   <link rel="stylesheet" href="/{{ cssFile }}" />
+
+   <script type="module" src="/{{ manifest[name].file }}"></script>
+
+   <!-- for chunk of importedChunks(manifest, name) -->
+   <link rel="modulepreload" src="/{{ chunk.file }}" />
+   ```
+
+   Specifically, a backend generating HTML should include the following tags given a manifest
+   file and an entry point:
+
+   - A `<link rel="stylesheet">` tag for each file in the entry point chunk's `css` list
+   - Recursively follow all chunks in the entry point's `imports` list and include a
+     `<link rel="stylesheet">` tag for each css file of each imported chunk.
+   - A tag for the `file` key of the entry point chunk (`<script type="moudle">` for Javascript,
+     or `<link rel="stylesheet">` for css)
+   - Optionally, `<link rel="modulepreload">` tag for the `file` of each imported Javascript
+     chunk, again recursively following the imports starting from the entry point chunk.
+
+   Following the above example manifest, for the entry point `main.js` the following tags should be included in production:
+
+   ```html
+   <link rel="stylesheet" href="assets/main.b82dbe22.css" />
+   <link rel="stylesheet" href="assets/shared.a834bfc3.css" />
+   <script type="module" src="assets/main.4889e940.js"></script>
+   <!-- optional -->
+   <link rel="modulepreload" src="assets/shared.83069a53.js" />
+   ```
+
+   While the following should be included for the entry point `views/foo.js`:
+
+   ```html
+   <link rel="stylesheet" href="assets/shared.a834bfc3.css" />
+   <script type="module" src="assets/foo.869aea0d.js"></script>
+   <!-- optional -->
+   <link rel="modulepreload" src="assets/shared.83069a53.js" />
    ```