Skip to main content

Development Workflow

This guide outlines the complete development workflow for building new features, from initial setup through staging deployment.

Prerequisites​

  • Node.js and npm/pnpm installed
  • Shopify CLI installed
  • Access to Linear for issue tracking
  • Access to BAO Cloudflare account
  • Access to development and staging Shopify stores

Getting Started​

1. Repository Setup​

First, clone the repository to your local machine:

git clone [repository-url]
cd [repository-name]

2. Environment Configuration​

Set up your Node.js environment and install dependencies:

# Use the specified Node.js version (if .nvmrc exists)
nvm use

# If no .nvmrc file exists, proceed directly to install
npm install
# or
pnpm install

Note: The (p)npm notation means you can use either npm or pnpm depending on your project's package manager.

Feature Development Workflow​

3. Issue Management​

Before starting development:

  1. Navigate to the corresponding issue in Linear
  2. Use the keyboard shortcut Cmd + Shift + . to copy the issue name
  3. Use this copied name as your branch name following the naming convention:
git checkout -b feature/support-1234-issue-description

Important: This naming convention automatically links your GitHub branch to the Linear issue for better tracking.

4. Development Environment Setup​

Configure your development environment:

# Configure Shopify app to use development settings
npm run shopify app config use

# Select shopify.app.toml when prompted
# This configuration points to the development environment

Note: The CLI will often prompt you to log in again during this process - this is normal behavior. Follow the authentication flow when prompted.

Start the development server:

npm run dev
# or
pnpm run dev

5. Authentication and Access Issues​

If you encounter authentication prompts, follow the login flow. You may see an access error message like:

Looks like you don't have access to this dev store: your-store (https://your-store.myshopify.com)
If you're not the owner, create a dev store staff account for yourself

Solution: Navigate to the store's admin panel via the partners dashboard, This should resolve the access issue. This wont work if you try and go to https://your-store.myshopify.com/admin. This will say you do not have access.

Important: The Shopify CLI frequently prompts for re-authentication, especially when switching between different environments or after periods of inactivity. This is normal behavior - simply follow the login prompts when they appear.

6. Scope Management​

When you need to update app permissions:

  1. Add the required scopes to the shopify.app.toml file
  2. Deploy the changes to make scopes available on the dev store:
npm run shopify app deploy
info

npm run shopify app deploy updates the app configuration and permissions on Shopify's platform, making new scopes available to your development store.

7. Building Shopify Functions​

Prerequisites​

  • Going forward we will be building functions in Rust due to the performance gains. To be able to run rust make sure that:
    • rust is installed - do not install rust with homebrew as this wont work.
      • use curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    • run rustup target add wasm32-wasip1

When working with Shopify Functions (discount functions, cart transforms, etc.):

  1. Create your function using the Shopify CLI:
shopify app generate extension

  1. Develop your function following Shopify's function development patterns

  2. Critical Step - Immediate Deployment: After creating or modifying a functions .toml file, you must deploy to the dev app:

npm run shopify app deploy

Why this is crucial: Shopify stores need to register new or modified functions .toml files before they can be used or configured. Without this deployment step:

  • The function won't appear in the Shopify admin
  • You won't be able to test or configure the function
  • The store won't recognize the function exists
  1. Verify function registration: After deployment, check the Shopify admin to confirm your function appears in the relevant settings (e.g., Discount settings for discount functions)

Important: This immediate deployment requirement is specific to functions - regular code changes can be developed and tested locally before deployment, but functions must be registered with Shopify to be usable.

Staging Deployment​

Once your feature is complete and ready for testing in a staging environment:

8. Branch Management​

# Switch to the staging branch
git checkout staging

# Merge your feature branch
git merge feature/support-1234-issue-description

9. Configuration Updates​

If you've added new scopes during development:

  1. Copy the new permissions from your development config to shopify.app.staging.toml
  2. Update the Cloudflare Workers configuration (Detailed below)

10. Cloudflare Workers Configuration​

To update scopes in Cloudflare:

  1. Navigate to BAO Cloudflare Dashboard

    • Click on Compute (Workers)
    • Select Workers and Pages
    • Find the correct application

  2. Update Scopes

    • Go to Settings
    • Edit the SCOPES secret
    • Click Rotate
    • Paste the comma-separated scope values (example format):
      read_customers,read_locales,read_markets,read_products,read_shipping,write_checkout_branding_settings,write_discounts,write_files,write_metaobject_definitions,write_metaobjects
    • Save the changes

11. Environment Configuration Switching​

Critical Step: Switch your Shopify CLI configuration to staging:

# Configure Shopify app for staging
npm run shopify app config use

# Select shopify.app.staging.toml when prompted
info

The CLI may prompt you to log in again during this configuration switch - this is normal behavior. Always authenticate when prompted.

12. Deployment Verification​

Before deploying, verify your configuration: Confirm the application_url in shopify.app.staging.toml points to the correct staging worker.

13. Deploy to Staging​

Execute the deployment process:

# Deploy the application code to Cloudflare Workers
npm run deploy
info

npm run deploy builds and deploys your application code to Cloudflare Workers. This updates the actual running application code.

# Deploy app configuration and permissions to Shopify
npm run shopify app deploy
info

npm run shopify app deploy updates the app's configuration, permissions, and metadata on Shopify's platform. This does not deploy your application code.

Switching Back to Development​

When returning to development work after staging deployment:

14. Configuration Reset​

warning

Always switch your configuration back to development:

# Switch back to development configuration
npm run shopify app config use

# Select shopify.app.toml when prompted (NOT the staging config)
info

The CLI will likely prompt you to log in again when switching configurations - this is expected behavior.

Understanding the Two Deploy Commands​

npm run deploy​

  • Purpose: Deploys your application code to Cloudflare Workers
  • What it does:
    • Builds your application bundle
    • Uploads the compiled code to Cloudflare Workers
    • Updates the running application with your latest code changes
  • When to use: Every time you make code changes that need to be live

npm run shopify app deploy​

  • Purpose: Updates app configuration and permissions on Shopify's platform
  • What it does:
    • Syncs app metadata (name, description, etc.)
    • Updates app permissions/scopes
    • Configures webhooks and other Shopify-specific settings
    • Does NOT deploy your application code
  • When to use: When you change app configuration, add new scopes, or modify TOML settings

Final Result​

After completing these steps, your changes will be available on the staging app, which can be installed on any store for testing purposes.

Troubleshooting​

  • Authentication Issues: Always ensure you're logged into the correct Shopify store admin
  • Frequent Login Prompts: The Shopify CLI regularly prompts for re-authentication - this is normal security behavior
  • Wrong Environment: If commands aren't working as expected, verify you're using the correct config file (npm run shopify app config use)
  • Scope Errors: Remember to update both the TOML file and Cloudflare Workers when adding new permissions
  • Deployment Failures: Verify that your application_url in the staging configuration matches your Cloudflare Worker URL
  • Code Changes Not Reflecting: If your code changes aren't showing up, you may need to run npm run deploy to update Cloudflare Workers
  • Permission Errors: If you're getting permission errors, you may need to run npm run shopify app deploy to sync the latest scopes
  • Development Issues After Staging: Always remember to switch back to development config using npm run shopify app config use and select shopify.app.toml

Best Practices​

  • Use npm run shopify, although just shopify will work if the Shopify cli is installed globally. Each project will have the cli in the dependencies though so the version may differ to what you have installed globally.
  • Always create feature branches with descriptive names linked to Linear issues
  • Test thoroughly in the development environment before moving to staging
  • Keep staging and development configurations synchronized
  • Document any new scopes or configuration changes for team members
  • Remember: npm run deploy for code changes, npm run shopify app deploy for configuration changes
  • Run both deploy commands when moving to staging to ensure both code and configuration are up to date
  • Always switch back to development configuration after staging deployment using npm run shopify app config use
  • Accept authentication prompts as normal CLI behavior - don't try to bypass them
  • Double-check which configuration file you're using if commands behave unexpectedly

Configuration Management Checklist​

Before starting any development work, verify:

  • You're on the correct git branch
  • You're using the correct Shopify app configuration (npm run shopify app config use)
  • You've authenticated with the CLI when prompted
  • Your local environment is pointing to the right store/app

When switching between environments:

  • Run npm run shopify app config use and select the appropriate .toml file
  • Accept any authentication prompts
  • Verify the configuration switch was successful
  • Test a simple command to confirm connectivity