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 local theme editor
salla theme dev opens the local theme editor at /__twilight/editor, laid out like the theme editor in the Salla dashboard: the first storefront page a browser loads after the dev server starts opens inside the editor, and so does / at any time. After that, storefront pages such as /ar and /en load on their own (add ?editor=off to skip the editor), and their ⚙ button opens the editor on the page you are looking at. The editor reads twilight.json, so you can try your theme the way a merchant would, with no dashboard. See Settings.
- Top bar: the theme's name, a phone/desktop switch (phone first, at a phone's real size), the preview switch, the language, reload, and a link to open the page on its own.
- Side panel toggle (top of the side rail): hides the side panel to give the preview more room, and shows it again. The editor remembers your choice. Clicking a tab while the panel is hidden opens the panel on that tab.
- Page elements (home icon): take over the home page's elements, then add any component
twilight.jsondeclares (Add new element opens a searchable gallery of them, with each component'simageandicon), remove, duplicate and reorder elements (drag them or use the arrows), and click one to scroll the preview to it and edit its fields. Collections (slides, links, reviews) are edited item by item: add, remove and reorder items within the limitstwilight.jsonsets. Product, category and brand fields, and links, are picked from your dev store (with samples when it has none). Image fields take a URL or a picture from your computer (PNG, JPEG, WebP, GIF or AVIF, up to 5 MB), which the dev server keeps intwilight-preview-assets/next totwilight.json. Customize starts from the elements the store shows; Start from an empty page starts from nothing. - Theme settings (second icon): change any theme setting. Editing anything turns the preview on.
- Fetch fresh store data (bottom of the side panel): the dev server reuses the store's settings for up to an hour (why), and the panel says when they were last fetched. This asks Salla for them again and reloads the preview, so a change you made in the dashboard shows now.
- In the preview: hover a home element for its bar: edit, move up or down, duplicate, add after it, or delete it, with the change shown at once and saved to
twilight.preview.json. On the store's own elements, the first action takes them over, as Customize does. Double-clicking an element edits it. Hovering the header or footer shows an edit button that opens the theme settings. The merchant's editor shows the same bar, plus hide.
The storefront runs in a frame, so the phone view uses your theme's own mobile breakpoints. The editor follows the storefront's language: Arabic pages get an Arabic, right-to-left editor.
Your changes save to twilight.preview.json next to twilight.json, so they survive reloads and are already on the first render. Both are gitignored. Only pages on the dev server itself can write to them. Delete twilight.preview.json to start over, or edit it by hand and the page reloads. To see how the merchant's own editor handles your theme, use the theme editor instead.
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