ShopiFast

Getting started with Remix

1. Clone the Repository

Clone the repository to your local machine:

git clone https://github.com/shopifast/remix-app
cd remix-app

2. Install Dependencies

Install all required dependencies:

pnpm install

Note: If you prefer npm, you can use npm, yarn instead, but we recommend pnpm for consistency.

3. Set Up Environment Variables

Copy the example environment file and configure it:

cp .env.example .env

Open the .env file in your preferred editor and update the following variables:

# PostgreSQL database connection URL
DATABASE_URL=postgres://default:secret@localhost:5432/shopifast?schema=public

# Slack webhook URL for sending notifications
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/your/webhook/url

# Redis connection URL
REDIS_URL=redis://localhost:6379

# OpenAI API key for accessing AI services
OPENAI_API_KEY=sk-proj-your-openai-api-key-here

Environment Variable Details:

  • DATABASE_URL: PostgreSQL connection string for your database
  • SLACK_WEBHOOK_URL: Optional webhook URL for Slack notifications
  • REDIS_URL: Redis connection string for caching and session management
  • OPENAI_API_KEY: Your OpenAI API key for AI-powered features (get yours from OpenAI Platform)

4. Database Setup

You have two options for the database:

Option A: Local Database with Docker (Recommended for Development)

Start the PostgreSQL database using Docker:

docker compose up -d

This will create a local PostgreSQL instance accessible at localhost:5432.

Option B: Cloud Database

If you prefer using a cloud database (like Supabase, Railway, or PlanetScale), update the DATABASE_URL in your .env file with your cloud database connection string.

5. Run Database Migrations

Apply the database schema:

pnpm db:migrate

Troubleshooting: If you encounter migration errors, ensure your database is running and the DATABASE_URL in your .env file is correct.

6. Seed the Database

Populate the database with initial data (plans and sample coupons):

pnpm db:seed:dev

This command adds:

  • Default subscription plans (required for app installation)
  • Sample discount coupons (for development and testing)

Shopify App Configuration

7. Create Your Shopify App

You have two options to create your Shopify app:

Option A: Using Shopify CLI (Recommended)

  1. Link your local project to a new Shopify app:
shopify app config link
  1. When prompted:
    • Select Yes, create it as a new app
    • Enter a descriptive name for your app (e.g., "My Awesome App - Dev")
    • Choose your Partner organization if you have multiple

Option B: Using Partners Dashboard

  1. Go to your Shopify Partners Dashboard
  2. Click "Create app" → "Create app manually"
  3. Fill in your app details
  4. Note down your API key and secret
  5. Manually update your .env file with these credentials

Tip: We recommend the CLI method as it automatically configures your environment variables.

Configure App Permissions

After linking your app, Shopify will automatically create a shopify.app.toml configuration file in your project root. This file contains all your app's settings and permissions.

Important: You need to add the required access scopes for your app to function properly. Here's an example configuration file:

# Learn more about configuring your app at https://shopify.dev/docs/apps/tools/cli/configuration

client_id = "your_client_id_here"
name = "your_app_name"
handle = "your-app-handle"
application_url = "https://localhost:3458"
embedded = true

[build]
automatically_update_urls_on_dev = true
dev_store_url = "your-dev-store.myshopify.com"
include_config_on_deploy = true

[webhooks]
api_version = "2025-04"

[[webhooks.subscriptions]]
uri = "/webhooks"
compliance_topics = [
  "customers/data_request",
  "customers/redact",
  "shop/redact",
]

[[webhooks.subscriptions]]
topics = ["app_subscriptions/approaching_capped_amount"]
uri = "/webhooks/app/approaching_capped_amount"

[[webhooks.subscriptions]]
topics = ["app_purchases_one_time/update"]
uri = "/webhooks/app/one_time_purchase_updated"

[[webhooks.subscriptions]]
topics = ["app/scopes_update"]
uri = "/webhooks/app/scopes_update"

[[webhooks.subscriptions]]
topics = ["app_subscriptions/update"]
uri = "/webhooks/app/subscriptions_update"

[[webhooks.subscriptions]]
topics = ["app/uninstalled"]
uri = "/webhooks/app/uninstalled"

[access_scopes]
# Learn more at https://shopify.dev/docs/apps/tools/cli/configuration#access_scopes
scopes = "write_products, write_discounts, write_discounts_allocator_functions, read_products,customer_read_customers,customer_read_orders,customer_read_store_credit_account_transactions,customer_read_store_credit_accounts,unauthenticated_read_product_listings"

[auth]
redirect_urls = [
  "https://localhost:3458/auth/callback",
  "https://localhost:3458/auth/shopify/callback",
  "https://localhost:3458/api/auth/callback",
]

[pos]
embedded = false

[mcp.customer_authentication]
redirect_uris = ["https://your-domain.com/callback"]

What are Access Scopes?

Access scopes define what your app can do in a Shopify store. The example configuration above includes scopes for:

  • Product Management: read_products, write_products
  • Discount Management: write_discounts, write_discounts_allocator_functions
  • Customer Data: customer_read_customers, customer_read_orders
  • Store Credit: customer_read_store_credit_account_transactions, customer_read_store_credit_accounts
  • Public Access: unauthenticated_read_product_listings

Common Scopes You Might Need

Depending on your app's functionality, you may need additional scopes:

[access_scopes]
scopes = "write_products,read_products,read_orders,write_orders,read_customers"
  • read_orders: View order information
  • write_orders: Modify orders
  • read_customers: Access customer data

Note: Only request the scopes your app actually needs. Requesting unnecessary permissions can make merchants hesitant to install your app.

Deploy Your Changes

After updating the shopify.app.toml file, you need to deploy the changes to Shopify:

pnpm run deploy

This command will:

  • Update your app configuration on Shopify
  • Apply the new access scopes
  • Sync any other configuration changes

Important: You'll need to reinstall your app in the development store after changing scopes, as existing installations won't automatically get the new permissions.

Learn more: For a complete list of available scopes, visit the Shopify CLI configuration documentation.

8. Start the Development Server

Launch your app in development mode:

pnpm dev

The CLI will:

  • Start your Remix development server
  • Automatically configure app URLs
  • Generate a secure tunnel for external access

9. Select Your Development Store

When prompted by the CLI:

  1. If you have an existing development store: Select it from the list
  2. If you need a new development store:

10. Configure App Exposure

Your app needs to be accessible from the internet for Shopify to communicate with it:

Option A: Automatic (Recommended)

  • When prompted, select (y) Yes, automatically update
  • Shopify will use Cloudflare tunnels to expose your app
  • URLs will be automatically updated in your configuration

Option B: Manual Tunnel

  • Select (n) No, never when prompted
  • Set up your own tunnel (e.g., ngrok, localtunnel)
  • Update the application_url and embedded_app_url in shopify.app.toml

Example using ngrok:

# In a separate terminal
ngrok http 3458

# Update shopify.app.toml with your ngrok URL
application_url = "https://your-ngrok-url.ngrok.io"
embedded_app_url = "https://your-ngrok-url.ngrok.io"

Deploy Your App Configuration

After running your app, the Shopify CLI will automatically generate and update your app's URLs. However, to ensure your app can properly receive webhooks and other network communications from Shopify, you need to deploy these configuration changes.

Deploy your changes to Shopify:

pnpm run deploy

When to Deploy

You need to run the deploy command when:

  • You change your app's URLs or network configuration
  • You're testing webhooks functionality
  • You modify settings in shopify.app.toml that affect how Shopify communicates with your app
  • You're switching between different tunnel services

You don't need to deploy for:

  • Code changes to your app's logic or UI
  • Database modifications
  • Local development and testing (non-network features)

Local Development Alternative

If you prefer to test your app using localhost (without tunneling), you can run:

pnpm run dev --use-localhost

Important Limitation: When using localhost, webhooks will not work because Shopify cannot reach your local development server from the internet. Use this option only when testing features that don't require webhooks or external communication.

Quick Reference

  • For webhook testing: Use pnpm run dev + pnpm run deploy
  • For UI/logic testing: Use pnpm run dev --use-localhost
  • After config changes: Always run pnpm run deploy

Testing Your App

Install Your App

  1. After running pnpm dev, you'll see a preview URL in your terminal
  2. Click the URL or copy it to your browser
  3. You'll be redirected to your development store
  4. Click "Install app" to install your app
  5. Grant the requested permissions

Verify Installation

  • Check that your app appears in the store's admin under "Apps"
  • Verify that database records are created (you can check your database)
  • Test basic functionality to ensure everything is working

Common Issues & Troubleshooting

Database Connection Issues

# Check if Docker containers are running
docker ps

# Restart Docker containers
docker compose down && docker compose up -d

# Verify database connectivity
pnpm db:status

App Installation Fails

  • Verify your .env file has correct credentials
  • Ensure your app URLs are accessible from the internet
  • Check that database migrations & seeders have been applied
  • Verify your app has the correct scopes in shopify.app.toml

Tunnel Connection Issues

  • Try restarting the development server
  • Check your internet connection
  • Consider using a manual tunnel service like ngrok

OpenAI Integration Issues

  • Verify your OPENAI_API_KEY is valid and has sufficient credits
  • Check that you're using the correct API key format (starts with sk-proj- or sk-)
  • Ensure your OpenAI organization has access to the models you're trying to use

Conclusion

Congratulations! You've successfully set up your Remix Shopify app. Your development environment is now ready, and your app is connected to your development store. You can start building your app's features and testing them in a real Shopify environment.

Webhooks

Previous Page

Security

Next Page