Edit in GitHubLog an issue

Change static assets directory

When you build a storefront project based on the Venia template, it copies the venia-static directory from the venia-ui package into your dist directory. This directory contains brand-specific files such as icons and the website's manifest.json file. To use a different set of these files, you will need to create a new static assets directory and copy it into dist during build time.

Tasks overview#

In this tutorial, you will:

  1. Create your own static assets directory
  2. Configure Webpack to copy that directory over during the build process
  3. Configure the UPWARD server to look for specific files in that directory
  4. Build and verify your changes

Create new static assets directory#

In your storefront project's root directory, run the following command to copy the venia-static directory from the venia-ui dependency into a new directory called my-static-assets:

Copied to your clipboard
cp -r node_modules/@magento/venia-ui/venia-static my-static-assets

NOTE: If your project does not have the node_modules directory, run yarn install.

Update manifest file#

Replace the Venia icons in that directory with your own icons and update the manifest.json file to reflect those changes:

Copied to your clipboard
1 {
2- "name": "Venia",
3- "short_name": "Venia",
4+ "name": "My Storefront",
5+ "short_name": "Storefront",
6 "start_url": "/",
7 "theme_color": "#1F39FF",
8 "display": "standalone",
9 "background_color": "#fff",
10- "description": "Shop the look",
11+ "description": "This is my example storefront",
12 "icons": [
13 {
14- "src": "/venia-static/icons/venia_circle_144.png",
15+ "src": "/my-static-assets/icons/my-storefront_144.png",
16 "sizes": "144x144",
17 "type": "image/png"
18 },
19 {
20- "src": "/venia-static/icons/venia_circle_192.png",
21+ "src": "/my-static-assets/icons/my-storefront_192.png",
22 "sizes": "192x192",
23 "type": "image/png"
24 },
25 {
26- "src": "/venia-static/icons/venia_circle_512.png",
27+ "src": "/my-static-assets/icons/my-storefront_512.png",
28 "sizes": "512x512",
29 "type": "image/png"
30 },
31 {
32- "src": "/venia-static/icons/venia_maskable_512.png",
33+ "src": "/my-static-assets/icons/my-storefront_maskable_512.png",
34 "sizes": "512x512",
35 "type": "image/png",
36 "purpose": "maskable"
37 }
38 ]
39 }

Update HTML template#

Your project's template.html file also contains references to Venia static assets which you may want to update. Edit this file and make the necessary changes to point these references to your new assets.

For example:

Copied to your clipboard
1- <link rel="apple-touch-icon" href="/venia-static/icons/venia_square_57.png">
2- <link rel="apple-touch-icon" sizes="180x180" href="/venia-static/icons/apple-touch-icon.png">
3+ <link rel="apple-touch-icon" href="/my-static-assets/icons/my-storefront_57.png">
4+ <link rel="apple-touch-icon" sizes="180x180" href="/my-static-assets/icons/apple-touch-icon.png">

Add copy instructions#

Now that you have a custom static assets directory in your project, you need to tell the build process to copy this directory into the dist folder when it runs. There are two main ways to do this: creating an entry in your project's upward.yml file or modifying the Webpack configuration file.

Using upward.yml (recommended)#

Open your project's upward.yml file and add the following entry:

Copied to your clipboard
1 status: veniaResponse.status
2 headers: veniaResponse.headers
3 body: veniaResponse.body
4
5+ myStaticIncludes:
6+ resolver: directory
7+ directory:
8+ resolver: inline
9+ inline: './my-static-assets'

During the build process, a Buildpack plugin for Webpack looks for valid resource paths in your upward.yml file and copies them into dist. Even though this object is not used anywhere during runtime, this entry declares the my-static-assets directory as a resource path to copy into dist.

Using Webpack directly#

You can also explicitly tell Webpack to copy the static assets directory over using a copy plugin. To do this, you need to install the copy-webpack-plugin dependency.

Copied to your clipboard
yarn add --dev copy-webpack-plugin@6.4.1

NOTE: Version 6.4.1 is used here instead of the latest because the current Venia template uses Webpack 4. If you updated your storefront project to use Webpack 5, you can use the latest version of the copy plugin.

Edit Webpack configuration#

In your project's webpack.config.js, add an import statement to the top of the file:

Copied to your clipboard
1 const HTMLWebpackPlugin = require('html-webpack-plugin');
2+ const CopyPlugin = require("copy-webpack-plugin");
3
4 module.exports = async env => {

Append the copy plugin to the plugin array of the Webpack configuration object:

Copied to your clipboard
1 new HTMLWebpackPlugin({
2 filename: 'index.html',
3 template: './template.html',
4 minify: {
5 collapseWhitespace: true,
6 removeComments: true
7 }
8 }),
9+ new CopyPlugin({
10+ patterns: [{ from: 'my-static-assets', to: 'my-static-assets' }]
11+ })
12 ];

This entry tells Webpack to copy the contents of the my-static-assets directory into a new my-static-assets directory in the dist folder during the build process.

Modify UPWARD configuration#

Now that the my-static-assets directory is inside dist, browsers can access these files under the /my-static-assets path. However, some files, such as robots.txt, manifest.json, and favicon.ico, must be located at the root. To serve these files from the root, you must configure the UPWARD server to look in the my-static-assets directory when it gets a request from these files.

Identify current rule#

The veniaResponse object in the base upward.yml file contains the conditional resolver that tells the server to resolve requests for these files using the staticFromRoot object. According to this object, the current rule for resolving requests for these files is to look for and return them from the venia-static directory.

Update UPWARD configuration using targets#

Since this rule is inside the primary upward.yml file in the venia-ui dependency, you cannot make direct edits to this file. However, you can use the transformUpward Buildpack target to make changes indirectly during the build process.

Open your project's local-intercept.js file and replace the content with the following:

Copied to your clipboard
1function localIntercept(targets) {
2 targets.of('@magento/pwa-buildpack').transformUpward.tap(def => {
3 def.staticFromRoot.inline.body.file.template.inline =
4 './my-static-assets/{{ filename }}';
5 });
6}
7
8module.exports = localIntercept;

The transformUpward target converts the base upward.yml file into a JavaScript object you can modify using an interceptor function. The interceptor function in the code sample provided sets the inline mustache template value with one that refers to the new static assets directory.

The build process generates the final upward.yml configuration under the dist directory, and the contents of this file is a combination of:

  • Content in the base upward.yml file in the venia-ui package
  • Modifications to that file using the transformUpward target
  • Content in your project's upward.yml file

Build and verify#

Use the build command to create a production build under the dist directory:

Copied to your clipboard
yarn build

After the build completes, open the dist directory and verify the following:

  1. A my-static-assets folder exists with the same content as the source.
  2. The upward.yml file contains the modifications described in the local intercept file

Use the start command to start the production server. This server runs using the production build inside the dist directory:

Copied to your clipboard
yarn start

Use your browser to navigate to your application and try to access the favicon.ico file from the root (<application URL>/favicon.ico). Your browser should return your new icon instead of the default Venia icon.

  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.