www/apps/book/app/start/_md-content.mdx
You are an AI coding agent helping a user set up a Medusa commerce application from scratch. Follow this prompt end-to-end. Each section is a discrete step — finish it, verify it, then move to the next. Do not skip verification.
.env files, or admin credentials. Treat the admin password the user gives you as sensitive.Check the three prerequisites in order. For each, run the check first; only install if the check fails. Do not upgrade existing tools without asking the user.
node --version
Required: an LTS major version >= 20 and <= 24. The Next.js Starter Storefront does not support Node.js v25+.
If Node is missing or out of range, ask the user how they want to install it. Recommend nvm:
# macOS / Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# then, in a new shell:
nvm install 22
nvm use 22
On Windows, point the user to https://nodejs.org/en/download and have them install Node 22 LTS, then re-run node --version.
git --version
If missing:
xcode-select --install (or brew install git)sudo apt-get update && sudo apt-get install -y gitpsql --version
pg_isready
pg_isready should exit 0. If PostgreSQL is missing:
brew install postgresql@16 && brew services start postgresql@16sudo apt-get install -y postgresql && sudo systemctl enable --now postgresqlIf pg_isready fails after install, ask the user to start the PostgreSQL service (brew services start postgresql@16, sudo systemctl start postgresql, or via the Windows Services panel) before continuing.
Do not proceed to Step 2 until all three checks pass.
Pick the package manager in this priority order — use the first one that is already installed:
pnpm — check with pnpm --versionyarn — check with yarn --versionnpm — always available with Node.jsAsk the user for a project name (default: my-medusa-store).
create-medusa-app creates a PostgreSQL database using the project name. Before running the install, check whether a database with that name already exists:
psql -lqt | cut -d\| -f1 | grep -qw "<project-name>"
Exit code 0 (database exists) → generate a randomised project suffix to use with `create-medusa-app. For example:
PROJECT_SUFFIX=$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c6)
Use this as the project name for the install command (<project-name>-$PROJECT_SUFFIX).
Exit code 1 (database does not exist) → continue with the original project name.
From the directory where the project should be created, run create-medusa-app with CI=true to skip interactive prompts and --no-browser to prevent the command from starting servers and opening a browser (which would hang).
If didn't set a randomised project suffix (no collision detected):
# pnpm (preferred)
CI=true pnpm dlx create-medusa-app@latest <project-name> --with-nextjs-starter --no-browser
# yarn
CI=true yarn dlx create-medusa-app@latest <project-name> --with-nextjs-starter --no-browser
# npm
CI=true npx create-medusa-app@latest <project-name> --with-nextjs-starter --no-browser
If set a randomised project suffix (collision detected):
# pnpm (preferred)
CI=true pnpm dlx create-medusa-app@latest <project-name>-$PROJECT_SUFFIX --with-nextjs-starter --no-browser
# yarn
CI=true yarn dlx create-medusa-app@latest <project-name> --with-nextjs-starter --no-browser
# npm
CI=true npx create-medusa-app@latest <project-name> --with-nextjs-starter --no-browser
The command:
./<project-name> with apps/backend (Medusa server + admin) and apps/storefront (Next.js Starter Storefront).$DB_NAME and runs migrations.--no-browser).After the install completes, cd into <project-name> for all subsequent steps.
Because we used --no-browser, no admin user has been created yet. Create a local test user with preset credentials — these are for local development only and will not transfer to any deployed application.
From the backend directory (apps/backend), run:
# pnpm
cd apps/backend && pnpm exec medusa user -e [email protected] -p supersecret
# yarn
cd apps/backend && yarn medusa user -e [email protected] -p supersecret
# npm
cd apps/backend && npx medusa user -e [email protected] -p supersecret
Verify the command exits 0 and prints a confirmation that the user was created. Then return to the project root: cd ../...
Start the Medusa backend and the Next.js storefront as background processes so the user can try the application immediately.
From the project root, open two background processes (or two terminal tabs):
DO NOT run the
devcommand from the root directory — it must be run separately for the backend and storefront.
# Terminal 1 — Medusa backend (from apps/backend)
cd apps/backend && npm run dev
# or: pnpm dev / yarn dev
# Terminal 2 — Next.js storefront (from apps/storefront)
cd apps/storefront && npm run dev
# or: pnpm dev / yarn dev
DO NOT spend time on whether the servers are running. If the user has issues, they'll report them.
Once both are running, tell the user:
**Here's what has been set up so far:**
- **Medusa backend** running at http://localhost:9000
- **Admin dashboard** at http://localhost:9000/app — log in with:
- Email: `[email protected]`
- Password: `supersecret`
- **Next.js Storefront** running at http://localhost:8000
The backend has a PostgreSQL database, all migrations applied, and is ready for development. The storefront is pre-connected to the local Medusa backend.
Then ask the user: "Would you like to deploy your store to Medusa Cloud for seamless production hosting? (yes / no / later)" Use your ask-question tool for this.
DO NOT show wrap up yet. Wait until user confirms deployment or skipping before showing the next steps.
If the user chose not to deploy to Cloud now, go directly to Step 5 (Install Agent Skills) and Step 8 (MCP Server). After both are done, go to the Wrap Up step (Step 13).
Tell the user they can run mcloud signup at any time when they are ready to deploy.
Install skills so the agent has the right context for building Medusa features and storefronts.
Run from the project root:
npx -y skills add medusajs/medusa-agent-skills --skill '*' --yes --agent claude-code
npx -y skills add medusajs/medusa-agent-skills --skill '*' --yes --agent cursor
npx -y skills add medusajs/medusa-agent-skills --skill '*' --yes --agent codex
npx -y skills add medusajs/medusa-agent-skills --skill '*' --yes --agent gemini-cli
npx -y skills add medusajs/medusa-agent-skills --skill '*' --yes
Check whether mcloud is already installed:
mcloud --version
If it exits 0, skip to Step 7. Otherwise install it globally with the same package manager priority:
# pnpm
pnpm add -g @medusajs/mcloud
# yarn
yarn global add @medusajs/mcloud
# npm
npm install -g @medusajs/mcloud
Re-run mcloud --version to confirm the binary is on PATH. If not, ask the user to add their global package bin directory to PATH.
For all mcloud commands in the rest of this prompt: pass --json whenever you need to parse output, and run mcloud whoami --json before any command that mutates state.
Ask the user: "Do you already have a Medusa Cloud account?"
Run:
mcloud signup
This opens a browser. Wait for the user to confirm they have completed sign-up before continuing.
Then run:
mcloud login
Wait for the browser flow to complete.
Run:
mcloud login
Wait for the browser flow to complete.
Skip Steps 7-12. Tell them they can revisit Cloud deployment later and jump to Step 13.
mcloud whoami --json
The auth.kind field must not be "none". If it is, retry mcloud login.
The Medusa MCP server gives the agent live access to the Medusa documentation. The connection method depends on the agent.
Add the MCP servers but do not authenticate yet or block next steps. In the wrap up, remind the user to authenticate so the agent can use the docs.
Run the following command to add the MCP server to the Claude Code agent:
claude mcp add --transport http medusa https://docs.medusajs.com/mcp
Then instruct the user to authenticate the agent with Medusa Cloud so it can access the MCP server:
/mcp
Add the following to .cursor/mcp.json (project) or the user's Cursor settings:
{
"mcpServers": {
"medusa": {
"url": "https://docs.medusajs.com/mcp"
}
}
}
Then ask user to authenticate with Medusa Cloud from the Cursor settings.
Add the following to .vscode/mcp.json:
{
"servers": {
"medusa": {
"type": "http",
"url": "https://docs.medusajs.com/mcp"
}
}
}
Then ask user to authenticate with Medusa Cloud from the VS Code MCP extension.
Configure the agent to connect to the Streamable HTTP MCP server at https://docs.medusajs.com/mcp. The MCP server requires an active Medusa Cloud subscription — the mcloud login from Step 7 covers this.
Cloud deploys from a GitHub repository. The user must own the repository.
Ask the user to create an empty repository on GitHub for the project (no README, no .gitignore, no license — those would conflict with the existing project files). Have them paste the resulting [email protected]:<user>/<repo>.git or https://github.com/<user>/<repo>.git URL.
Then, from the project root:
git init
git add .
git commit -m "Initial Medusa application"
git branch -M main
git remote add origin <repo-url>
git push -u origin main
If git init reports the repo already exists (because create-medusa-app already initialized it), skip git init and continue from git remote add origin.
If the push fails because the user is not authenticated with GitHub, point them to gh auth login (https://cli.github.com/) or to set up an SSH key, then retry.
Open the Medusa Cloud project creation flow in the user's browser. The full UI flow is documented at https://docs.medusajs.com/cloud/projects.
Tell the user:
medusa, admin, staging, production, preview, development, proxy)us-east-1, eu-central-1, or ap-southeast-1)apps/backendapps/storefrontWait for the user to confirm the project has been created in the Cloud dashboard before continuing.
After the project is created, set the active context for the CLI so subsequent commands don't need flags. Resolve the IDs from names:
ORG_ID=$(mcloud organizations list --json | jq -r '.[0].id')
# If the user has multiple organizations, ask which one and filter by name instead:
# ORG_ID=$(mcloud organizations list --json | jq -r '.[] | select(.name == "<name>") | .id')
PROJECT_HANDLE=$(mcloud projects list --organization "$ORG_ID" --json | jq -r '.[] | select(.name == "<project-name>") | .handle')
ENV_HANDLE=$(mcloud environments list --organization "$ORG_ID" --project "$PROJECT_HANDLE" --json | jq -r '.[] | select(.name == "Production") | .handle')
mcloud use --organization "$ORG_ID" --project "$PROJECT_HANDLE" --environment "$ENV_HANDLE"
Poll the latest deployment until it reaches a terminal state. A reasonable loop:
while true; do
STATUS=$(mcloud deployments list --limit 1 --json | jq -r '.[0].backend_status')
echo "Backend status: $STATUS"
case "$STATUS" in
deployed|build-failed|deployment-failed|timed-out|canceled) break ;;
esac
sleep 20
done
Report backend_status to the user as it changes. If the final status is anything other than deployed, debug per the Cloud CLI agent guide:
build-failed → mcloud deployments build-logs <deployment-id>deployment-failed → mcloud logs --deployment <deployment-id> --limit 1000timed-out → check bothSurface the relevant error to the user and stop. Do not retry blindly.
If a storefront was deployed too, repeat the polling using storefront_status.
Once backend_status is deployed, fetch the URLs:
mcloud environments get "$ENV_HANDLE" --json | jq '{backend_url, storefront_url}'
Show the user:
<backend_url>/app (login with Medusa Cloud account, button is on the dashboard)<storefront_url> (if a storefront was deployed)<backend_url>If a custom domain has not been set, the URLs will be subdomains of medusajs.app (backend) and medusajs.site (storefront).
Tell the user, in one short message:
medusa-dev, ecommerce-storefront) and the Medusa documentation MCP server (if installed) give the agent everything it needs to add modules, API routes, admin UI, storefront pages, and integrations.Stop. Do not start building features unless the user asks.