Skip to content
Browse documentation

Develop locally

nanodev is the command-line tool for working on your NanoSite store or website on your own computer, with your own editor and your own AI agent. It's made by nanosite.ai.

Your project stays one project. The code lives in a git repository on NanoSite, and nanodev keeps your folder and the cloud in sync. You can switch between the AI builder in the web and your local editor whenever you like.

nanodev is in beta. The packages are published on npm with the beta tag: @nanosite/nanodev (the CLI) and @nanosite/create-nanodev (npm create @nanosite/nanodev). Its source and the Claude Code plugin are on GitHub, where you can report a problem or suggest a feature.

Who can use it

  • Stores: on any plan.
  • Websites: need a paid subscription.

The same project limits apply as in the web. If your plan doesn't cover a project, nanodev tells you and links to the upgrade page.

What you need

  • Node.js 22.12 or newer, and npm.
  • git.
  • A NanoSite account.

Run nanodev doctor at any time to check git, Node.js, your login and your network.

Start a new store

One command creates a store and runs it on your machine:

npm create @nanosite/nanodev@beta my-store

It will:

  1. Log you in, if you aren't already. Your browser opens to approve it.
  2. Ask you to pick a template, or the starter kit.
  3. Create the store in your account, with demo products.
  4. Download the project into ./my-store and install its packages.
  5. Start the dev server and open your store in the browser.

The new store also shows up in your NanoSite dashboard. Run nanodev open to jump to it in the AI builder.

Work on an existing project

Install the CLI once:

npm install -g @nanosite/nanodev@beta

Check it worked with nanodev --version.

Log in

nanodev login

nanodev shows a short code and opens a page in your browser. Check the code matches, approve, and you're done. Your login also lets plain git talk to your projects, so git pull and git push work too. If git doesn't know your name and email yet, your project folders commit as your NanoSite login until you set your own; nanodev tells you when it does that.

Link a project

nanodev link

Pick a project from the list, or pass its id: nanodev link <project>. nanodev downloads the project into a folder, installs its packages and adds the files your AI agent reads (see Use your own AI agent).

Run the dev server

nanodev dev

For a store, pages are rendered on the server, the same way your live store does it (this is called server-side rendering, and it's what makes pages fast and visible to search engines). The dev server also has hot reload: save a file and the page in your browser updates.

For a website, this starts the website's dev server, also with hot reload.

nanodev prints the local address to open in your browser.

Live store data

Your local store shows real data from your store: products, collections, prices, stock, settings. The dev server forwards /api requests to NanoSite and adds your store's publishable key for you (the public key that tells NanoSite which store the request is for; it's safe to show in a browser). You don't need to copy keys or set environment variables.

Carts and shopper accounts work locally too. The dev server adjusts their cookies so they work on localhost.

Checkout is disabled in local dev. Requests that would place an order are refused with the message "Checkout is disabled in local dev, test it in your preview". Test checkout in a private preview instead. This way no real orders or payments come from your laptop.

On a website, form submissions sent from local dev are marked [local dev] so you can tell them apart.

When someone else makes changes

While it runs, nanodev dev checks for new commits every few seconds. When the AI builder or a teammate pushes, you'll see:

↓ 2 new commits on nano-site, run nanodev pull

nanodev never changes your files on its own. Run nanodev pull when you're ready. See Git workflow.

Use your own AI agent

There's no chat inside nanodev. Bring the agent you already use: Claude Code, Cursor, Codex, GitHub Copilot or any other.

When you create or link a project, nanodev writes:

  • AGENTS.md: what the project is, the folder layout, the nanodev commands and the rules that keep your store working (for example: don't edit dist or node_modules, keep pages working when rendered on the server, use the Ecommerce SDK for store data). Most agents read this file automatically.
  • CLAUDE.md: points Claude Code at AGENTS.md, so every agent reads the same rules.
  • .claude/settings.json: the first time you open the folder in Claude Code, it offers to install the nanodev plugin, with skills for the git workflow, stores, websites and fixing hydration errors (when the page rendered on the server doesn't match what the browser renders). The plugin comes from the nanosite plugin catalog; you can also add it yourself with /plugin marketplace add nanosite-ai/claude-plugins and /plugin install nanodev@nanosite.

nanodev refreshes AGENTS.md when you pull. It only rewrites its own section, so notes you add outside it are kept.

Next steps