Deploying Your Weaverse Hydrogen Project to Shopify Oxygen
Shopify Oxygen is a fully managed, serverless hosting platform for Hydrogen storefronts, offering global CDN, seamless Shopify integration, and zero infrastructure management. Deploying to Oxygen is the recommended way to launch your Weaverse Hydrogen project for maximum performance and reliability.
Prerequisites
- Shopify store (Plus plan for multiple storefronts; one storefront for non-Plus)
- Weaverse Hydrogen project ready in a GitHub repository
- Shopify CLI installed (install guide)
- GitHub account connected to your Shopify store
- Weaverse Project ID (from Weaverse Studio)
Deployment Steps
1. Install the Hydrogen App
Visit the Shopify Hydrogen App and install it in your Shopify store.
2. Create a GitHub Repository
- Existing Project: Commit and push your code to a new GitHub repository.
- New Project: Use the Weaverse Hydrogen template to create a new repo.
3. Set Up Your Storefront
In your Shopify admin, open the Hydrogen app and click "Create storefront" to begin setup.
4. Connect to Your Repository
- Select "Set up GitHub continuous deployment now."
5. Configure the Environment
- Wait for the Hydrogen app to create a pull request in your repo.
- In "Storefront settings," go to "Environments and variables."
- Add the
WEAVERSE_PROJECT_ID(from Weaverse Studio's Project Settings or project URL).
- Add any other required environment variables (see Environment Variables).
6. Merge the Pull Request
- Merge the PR created by the Hydrogen app to set up GitHub Actions for Oxygen deployment.
- If you merge before adding
WEAVERSE_PROJECT_ID, trigger a manual rebuild (npx shopify hydrogen deploy).
7. Publish Your Storefront & Update Weaverse Preview URL
After the GitHub Action completes:
- Make the storefront public: Click "..." next to the storefront name, select "Edit environment," then choose "Publish."
- Note: Shopify Plus plans can publish up to 25 Storefronts. Other plans are limited to one.
Additional Note: For Shopify Starter or Development plans, use Vercel or another platform, as the Hydrogen app cannot deploy to Oxygen.
Troubleshooting
- Missing environment variables: Ensure all required variables (like
WEAVERSE_PROJECT_ID) are set before merging the PR. - Build or deploy errors: Check the GitHub Actions logs for details. Re-run the workflow after fixing issues.
- Storefront not public: Remember to publish your storefront after deployment.
- Preview not updating: Make sure the Weaverse Preview URL is set to your Oxygen deployment.
Best Practices
- Keep secrets out of version control: Use environment variables for all sensitive data.
- Test locally before deploying: Run your Hydrogen app with the same environment variables as production.
- Monitor logs after deployment: Use GitHub Actions and Shopify dashboards to monitor for errors.
- Review environment variables regularly: Remove unused variables and update as your project evolves.
- Follow Shopify’s security guidelines: Shopify Hydrogen Security
Summary
Deploying your Weaverse Hydrogen project to Shopify Oxygen gives you a secure, scalable, and high-performance storefront. Follow the steps and best practices above for a smooth launch.