Deploying extensions

After creating your first extension, you can deploy it. In a Checkout extensions project, there are two deployment methods:

• Production Deploy: This deploys the extensions to your store in the production environment. It occurs each time a commit and push is made to the main branch.

• Preview Deploy: This generates an optimized production build but does not deploy it to your store. It occurs each time a commit and push is made to a branch other than main (e.g., feat/totalizer-extension).

Note

Keep in mind that using Discovery with WebOps is not required to deploy a Checkout extension. You can use WebOps exclusively to deploy Checkout extensions if needed.

Deploying to production

As explained above, a production deployment occurs each time you commit and push to your main branch. The process can be described in the following steps:

1. A commit and push to the main branch occurs.
2. FastStore WebOps receives a commit event from the repository.
3. FastStore WebOps detects the modules configured in the repository, in this case, the commit affects the Checkout module.
4. FastStore WebOps triggers a deployment pipeline build.
5. Once the build is completed, FastStore WebOps deploys the extensions to the VTEX infrastructure.
6. Within 5-10 minutes, the changes will be applied to your Checkout. This 5-10 minute range is needed for cache propagation.

You can monitor the deployment process by accessing the FastStore WebOps page in your Store’s account admin:

Note

Keep in mind that once a commit and push is made to the main branch, your changes will be applied to production. To revert this change, you need to create a new commit that reverts the previous changes and push it to main.

Preview deploys

Before pushing to production, we recommend generating a deploy preview. As explained above, deploy previews occur each time you commit and push to a branch other than main. The process for a deploy preview is the same as a production deployment, except that the changes won’t be applied to your store in production. This means the assets generated by this build are not accessed by your store in production.

These preview deployments are useful because they allow you to generate production builds without deploying to production, enabling you to test how the changes behave by instructing Checkout to load them instead of the production assets. To do this, you’ll need:

• The URL of your store’s Checkout in production (this could be a production or QA/dev account URL, like secure.store-a.com/checkout/cart)
• The build ID of the deployment preview. This deployment ID is the commit ID that triggered the preview deployment. See the instructions below for finding this commit ID.

With this information, you can access your Checkout and pass the build ID to it as a query string with __previewId. This will look something like:

https://secure.store-a.com/checkout/cart?__previewId=7fb760a66ae567f1eb2059cb3c3f01c1d4badca4

Note

In this release, deployment previews have limited functionality. You currently cannot access ready-made links to view extensions in your Store’s Checkout. Instead, you’ll need to manually locate the build ID and add it as a query string. We’re actively working on a seamless experience in WebOps to improve this workflow in future releases.

By passing this __previewId, you’re instructing Checkout to load the extensions from a specific deployment. This deployment does not necessarily need to be a preview deployment, it could also be a production deployment. This can be helpful for double-checking a previous production build that is no longer the default in production.

Finding the build ID

The build ID of a deployment is the commit SHA ID generated by Git. Here are a few ways to find the commit ID:

• Use the git log command and look for the commit <id> pattern. For example:

commit 9eeae390cf57b07a018713716ebc71cd020073e8 # ⬅️ This is the commit ID
Author: Marcos Oliveira <marcos.oliveira@vtex.com>
Date:   Fri Oct 25 16:08:38 2024 -0300

Updated totalizer

• Use GitHub, as shown in the following screenshot, and click on “Copy full SHA commit” to get the commit ID:

Handling Build Failures

If your build fails, the issue likely originates from an error in your extension’s code or configuration. Common causes include type-checking issues or simple typos. When this happens, FastStore WebOps will show that a build has failed, but Checkout build logs won’t be accessible in FastStore WebOps.

For this release, detailed build logs are available directly in your GitHub repository. To locate them:

1. Go to your GitHub repository and find the latest commit where the build failed.
2. Access the build logs by clicking on the “✔️”, ”❌” or ”🟡” icon next to the commit description, to see the GitHub Checks for that commit.
3. Look for “FastStore WebOps” and select the “Details” link.

This will display the build log, as shown in the screenshot below.

Another way to check a failed build is by running the build command locally. You can use the FastStore CLI for this:

yarn fsp build <account-name> checkout

This command runs the build process for Checkout extensions in the specified account and displays any errors that occur during the build. If no errors appear locally, check your GitHub repository to identify any potential issues with your build workflow.