Getting Started with Medusa DTC Starter

In this guide, you'll learn how to install Medusa DTC Starter by Gorgo, configure both apps, and connect your first integration.

• Node.js v20 or later
• PostgreSQL v15 or later
• npm, yarn, or pnpm

Install the starter one of two ways: scaffold a new project with Medusa's own CLI, or clone the repository and configure each app by hand.

yarn dlx create-medusa-app@latest --repo-url https://github.com/gorgojs/medusa-dtc-starter

--repo-url tells create-medusa-app to scaffold from the specified repository instead of the official Medusa starter, but the usual prompts for a project name and a database stay the same. By default, the command also runs migrations, creates an admin user, and seeds the database. Pass --no-migrations to skip all three.

1. Clone the repository and install dependencies:

   yarnpnpmnpm

   1git clone https://github.com/gorgojs/medusa-dtc-starter.git
   2cd medusa-dtc-starter
   3yarn install

2. Create the backend's environment file and point DATABASE_URL at a real database:

   Terminal
   cp apps/backend/.env.template apps/backend/.env

   apps/backend/.env
   DATABASE_URL=postgres://postgres:@localhost:5432/medusa-dtc-starter

3. Run the migrations, create an admin user, seed the initial data, and start the backend:

   yarnpnpmnpm

   1cd apps/backend
   2yarn medusa db:migrate
   3yarn medusa user -e admin@medusajs.com -p supersecret
   4yarn seed
   5yarn dev

4. Open the Admin dashboard at http://localhost:9000/app, log in, and copy the publishable API key from Settings → Publishable API Keys.

5. Create the storefront's environment file with that key:

   Terminal
   cp apps/storefront/.env.template apps/storefront/.env.local

   apps/storefront/.env.local
   NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_6c3...

6. Start the storefront:

   yarnpnpmnpm

   1cd apps/storefront
   2yarn dev

The storefront runs at http://localhost:8000. The repository root is set up for pnpm, so pnpm dev there starts both apps at once. With npm or yarn, start each app from its own directory.

Before the backend can run, set a real value for DATABASE_URL and INTEGRATION_ENCRYPTION_KEY:

apps/backend/.env
1DATABASE_URL=postgres://postgres:@localhost:5432/medusa-dtc-starter
2INTEGRATION_ENCRYPTION_KEY=supersecret

INTEGRATION_ENCRYPTION_KEY encrypts the secret fields the Integration Module stores. Change the supersecret value before production.

For the storefront, you need at least the publishable API key from your Medusa backend:

apps/storefront/.env.local
1NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_6c3...
2NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
3NEXT_PUBLIC_DEFAULT_REGION=en
4NEXT_PUBLIC_BASE_URL=https://localhost:8000
5NEXT_PUBLIC_STRIPE_KEY=
6MEDUSA_CLOUD_S3_HOSTNAME=
7MEDUSA_CLOUD_S3_PATHNAME=
8NODE_ENV=development
9REVALIDATE_SECRET=supersecret
10NEXT_PUBLIC_SITE_NAME="Gorgo Medusa Store"
11NEXT_PUBLIC_ADDRESS_AUTOCOMPLETE_PROVIDER=dadata
12NEXT_PUBLIC_ADDRESS_AUTOCOMPLETE_PROVIDER_API_KEY=

The rest already ship with working localhost defaults. NEXT_PUBLIC_SITE_NAME sets the store name shown in the header, footer, and checkout, and it also feeds the schema.org markup and the llms.txt endpoint. NEXT_PUBLIC_STRIPE_KEY is only needed if you use Stripe. NEXT_PUBLIC_ADDRESS_AUTOCOMPLETE_PROVIDER_API_KEY is only needed for the built-in address autocomplete, see the Set Up Address Autocomplete documentation. MEDUSA_CLOUD_S3_HOSTNAME and MEDUSA_CLOUD_S3_PATHNAME are only needed when deploying to Medusa Cloud. REVALIDATE_SECRET has to match the same variable in apps/backend/.env, because the backend sends that value with every revalidation webhook. Change it before production.

The Integration Module (@gorgo/medusa-integration) is already registered in medusa-config.ts with an empty providers array, so there's nothing to wire up before you can add one. Once the backend is running, add a payment, fulfillment, or ERP integration and configure it from Medusa Admin, see the Browse and Add an Integration documentation.

If the storefront's logs show Error fetching regions. Did you set up regions in your Medusa Admin and define a NEXT_PUBLIC_MEDUSA_BACKEND_URL environment variable., the cause is one of two things: either NEXT_PUBLIC_MEDUSA_BACKEND_URL isn't set or points to the wrong place, or the backend has no region configured yet. Check that the backend is running and reachable at that URL. If there really are no regions, the seed script creates several, see the Customize Seed Data documentation.

Stripe key is missing. Set NEXT_PUBLIC_STRIPE_KEY environment variable. means the storefront tried to render Stripe Elements without a Stripe publishable key set. Stripe client secret is missing. Cannot initialize Stripe. means no Stripe payment session exists on the cart yet. This usually happens because the selected region has no Stripe provider configured.

If the address field doesn't suggest anything as you type during checkout, the DaData key is probably missing. Create an account on DaData, set your key in NEXT_PUBLIC_ADDRESS_AUTOCOMPLETE_PROVIDER_API_KEY, and leave NEXT_PUBLIC_ADDRESS_AUTOCOMPLETE_PROVIDER set to dadata. See the Set Up Address Autocomplete documentation for configuring autocomplete and connecting a different provider.

STORE_CORS, ADMIN_CORS, and AUTH_CORS in the backend's .env are allow-lists. If you move the storefront or Admin to a different port or domain, add that origin to the matching variable and restart the backend.