create-custom-origin is a
buildpack CLI subcommand which creates a unique local hostname and trusted SSL certificate for your project.
Usage example with
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.
Note: This command should be used only in a development environment and never as part of a production deployment process.
Why PWA development requires a secure custom origin
HTTPS is required
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.
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.
PWADevServer uses OpenSSL to generate these certificates; your operating system must have an
openssl command of version 1.0 or above to use this feature.
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.
Use environment variables in the
CUSTOM_ORIGIN_ namespace to change the behavior of the
|Environment Variable Name||Default Value||Description|
||Enable the custom origin feature|
||Add a unique hash string to the custom origin.|
||Allows you to manually specify the subdomain prefix of the custom origin instead of using the package name.|
||Allows you to specify the exact domain of the custom origin instead of a subdomain under
Set these variables permanently in your
.env file, or argue them at the command line for overrides:
CUSTOM_ORIGIN_EXACT_DOMAIN="my.pwa" \ npx @magento/pwa-buildpack create-custom-origin .
CUSTOM_ORIGIN_ADD_UNIQUE_HASH is set to
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.