Edit in GitHubLog an issue

Create custom origin

The create-custom-origin is a buildpack CLI subcommand which creates a unique local hostname and trusted SSL certificate for your project.

Example#

Usage example with npx:

Copied to your clipboard
npx @magento/pwa-buildpack create-custom-origin <dir>

This feature requires administrative access, so it may prompt you for an administrative password at the command line. It does not permanently elevate permissions for the dev process, but instead, it launches a privileged subprocess to execute one command.

Benefits of a custom origin#

Developing a storefront with a custom origin provides the following benefits:

Enables HTTPS#

Some PWA features, such as ServiceWorkers and Push Notifications, are only available on HTTPS secure domains. Some browsers make exceptions for the domain localhost, but this is non-standard.

HTTPS development is becoming the norm, but creating a self-signed certificate and configuring your server and browser to support this is a complex process.

The create-custom-origin command automates this process reliably on most operating systems. It uses devcert to edit your local hostfile, create and manage certificates, and try to configure web browsers to "trust" the certificate. This prevents security errors from showing up in browsers.

In the future, browsers will require trust, as well as SSL itself, to enable some features.

Unique domains prevent ServiceWorker collisions#

PWA features, such as ServiceWorkers, use the concept of a 'scope' to separate installed ServiceWorkers from each other. A scope is a combination of a domain name, port, and path. If you use localhost for developing multiple PWAs, you run the risk of Service Workers overriding or colliding with each other.

Customization#

Use environment variables in the CUSTOM_ORIGIN_ namespace to change the behavior of the create-custom-origin command.

Environment Variable NameDefault ValueDescription
CUSTOM_ORIGIN_ENABLEDtrueEnable the custom origin feature
CUSTOM_ORIGIN_ADD_UNIQUE_HASHtrueAdd a unique hash string to the custom origin.
CUSTOM_ORIGIN_SUBDOMAINAllows you to manually specify the subdomain prefix of the custom origin instead of using the package name.
CUSTOM_ORIGIN_EXACT_DOMAINAllows you to specify the exact domain of the custom origin instead of a subdomain under .local.pwadev.

Set these variables permanently in your .env file, or argue them at the command line for overrides:

Copied to your clipboard
1CUSTOM_ORIGIN_EXACT_DOMAIN="my.pwa" \
2npx @magento/pwa-buildpack create-custom-origin .

Unique hash#

If CUSTOM_ORIGIN_ADD_UNIQUE_HASH is set to true, the create-custom-origin command adds a unique hash string to the custom origin. This string is based on the filesystem location.

This naturally separates domains when running multiple project folders on one developer machine.

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