Run it locally
Start the dev server with salla theme dev, and what the options and the first render do.
Run salla theme dev from your theme folder every day you work on the theme.
Framework: TanStack Start
The files named below (app/router.tsx, app/routes.ts) belong to TanStack Start, the default and currently supported framework. See what depends on the framework.
salla theme devWhat happens
- It checks the toolchain.
- It restores anything missing, so it also works on a fresh clone. A missing
.envis written with the demo store, and a missingnode_modulestriggerspnpm install. - It picks a free port, starting at 5173, and tells you if it had to use another.
- It starts Vite on that port.
- It waits until the storefront really renders. The first request compiles the server code, about ten seconds.
- It opens your browser. Press
Ctrl+Cto stop.
Open the right address
The storefront lives under a language prefix:
| URL | Result |
|---|---|
http://localhost:5173/ar | Arabic, right to left |
http://localhost:5173/en | English |
http://localhost:5173/ | Not the storefront. A small shell that hands over in the browser. |
The CLI opens /ar?storeId=<id> for you. See Link a store.
Options
| Option | Meaning |
|---|---|
-p, --port <port> | Start looking for a free port from this one. |
-s, --store [store] | Bind a store. With an id it binds directly, without a value it asks. |
--no-open | Do not open the browser. |
-e, --editor | Open the merchant theme editor around the dev server. See Theme editor. |
Pass options to salla theme dev, not after pnpm dev --. Vite ignores anything forwarded after a bare --.
Edit and see it
Saving a file updates the browser.
| You edit | Where |
|---|---|
| Components and sections | app/components/ |
| Replace engine components | app/router.tsx |
| Add or override pages | app/routes.ts |
| Translations | locales/ar.json, locales/en.json |
| Settings and home blocks | twilight.json |
What is in the project explains each file.
The dev settings panel
In development the page shows a small floating panel. It reads twilight.json, so you can flip a merchant setting or edit a home block and watch the page react, with no dashboard. See Settings.
Run without the CLI
Inside the theme folder, plain Vite works too:
pnpm devIt uses the store in .env, or the one in the URL's ?storeId=.
When the storefront does not render
If the page shows "Store is temporarily unavailable", the store in .env returned nothing. The CLI prints this and keeps the server running. Pick another with salla theme dev --store. More fixes: Troubleshooting.
Next: Link a store