ScandiPWA extensions are NPM packages, which are installed as a dependency of a project, which is recognized by ScandiPWA as an extension. Extensions enable developers to ship plug-an-play features of a store (i.e. Social Login, Payment Method). Extensions provide a wide range of extensibility features to modify a default behavior of a store or to add new features to it.

Official ScandiPWA extensions are distributed using marketplace.scandipwa.com. There, developers can download, and install existing extensions (from NPM, or using ZIP) or report issues and request extension development.disable

How are extensions recognized?

For an NPM package to be considered an extension, it must have a package.json field scandipwa.type equal to extension. For example:

{
    "scandipwa": {
        "type": "extension"
    }
    ...
}

<aside> ℹ️ package.json is a file that contains relevant and human-readable metadata about the project and specifies a set of dependencies for NPM.

</aside>

How to make an NPM package be recognized as an extension?

Both themes and extensions can register extensions. In order to do it, the extension should be added to scandipwa.extensions object of package.json . The extension must be a valid NPM package, therefore you are required to add it into dependencies field of your package.json.

{
    "dependencies": {
        "@scandipwa/m2-theme": "0.0.2",
        ...
    },
    "scandipwa": {
        "extensions": {
            "@scandipwa/m2-theme": true
        },
        ...
    }
    ...
}

Enabling and disabling an extension is achieved by setting the trueor false as a value of the extension key in scandipwa.extensions . Your theme can control enabled extensions across the whole application. This allows disabling the previously enabled extension. The sequence of discovering enabled extensions is as follows:

  1. Your theme-enabled extensions
  2. Your theme's parent themes enabled extensions
  3. Extension enabled extensions

<aside> ⚠️ Watch out! Disabling a previously enabled extension can lead to layout-shifts and issues inside of your parent theme. Also, there might be extensions plugging into the extension you intend to disable, this can lead to unexpected results.

</aside>

What extensibility features do extensions provide?

The extensions are power-less without a theme. The application compiles from theme sources. Extensions are just isolated pieces, which make some features of your application work. Extensions enable the following extensibility features of ScandiPWA:

How to install an extension from the marketplace using NPM?

This is the recommended way of extension installation. This type of installation prohibits you to modify the package source and enables upgrades via NPM.

  1. Make sure you have an NPM token generated in My Account / NPM Auth tokens section of the marketplace
  2. Find the package name matching your extensions in My Account / NPM packages section of the marketplace
  3. Create the .npmrc file with the following contents, inside of your ScandiPWA root folder://r.scandipwa.com/:_authToken=<NPM_AUTH_TOKEN>@scandiweb:registry=https://r.scandipwa.com/always-auth=true
  4. Copy the NPM auth token, and replace the <NPM_AUTH_TOKEN> template in .npmrc with your NPM token
  5. Add the extensions package to your project's dependencies, use one of the commands:
    1. You can use Yarn: yarn add <PACKAGE>
    2. Or use NPM: npm i <PACKAGE>
  6. Change the scandipwa.extensions field in ScandiPWA root package.json to include extensions enablement entry, for example: "@scandiweb/my-extension": true
  7. Run your app as usual, it should start and have a an extension functionality enabled

How to install an extension from the marketplace from ZIP?

This type of installation enables you to modify the package source, but prevents further upgrades.

  1. Create (or make sure it exists) a packages folder inside of your ScandiPWA root
  2. Download the package from My Account / My Downloadable Products section of the marketplace
  3. Unzip the package into the newly created folder
  4. Make sure the package.json file is found in packages/<UNZIPPED FOLDER>, for example, packages/my-extension.
  5. Copy the name field from the extensions package.json file
  6. Edit the ScandiPWA root package.json to include the package name as a dependency, in version place specify the relative path to the root of the extension prefixed with file: for example, file:./packages/my-extension. In the end dependencies field in the package. json must include a similar entry: "@scandiweb/my-extenion": "file:./packages/my-extension"
  7. Make sure the ScandiPWA root package.json includes "postinstall": "scandipwa-scripts link", and "postupdate": "scandipwa-scripts link" entries in the scripts field
  8. Change the scandipwa.extensions field in ScandiPWA root package.json to include extensions enablement entry, for example: "@scandiweb/my-extenion": true
  9. To install dependencies, use one of the commands:
    1. You can use Yarn: yarn
    2. Or use NPM: npm i
  10. Run your app as usual, it should start and have an extension functionality enabled

How to request a new extension or report an issue?

Please use the following form to report issues or request a new extension from the Marketplace team.

How to create an extension through ScandiPWA CLI?

You can use the following command:

extension create

Creates a new scandiPWA extension.

Syntax:

scandipwa extension create [--no-enable] <name>

Options:

Tutorials

Tutorial: Create and register a new extension

Tutorial: Upgrading an extension from 3.x to 4.x

2090