Requirements
- Node.js 22+ (
better-sqlite3requires it as of v13). 22 (LTS) is the tested baseline - CI, Docker, and.nvmrcall pin it - butbetter-sqlite3,argon2, andsharpall ship N-API prebuilt binaries now, so newer versions (e.g. 26) work fine too. - npm
Note
On a platform/Node combination with no prebuilt binary available, those three packages fall back to a from-source compile, which needs a C++ toolchain (build-essential on Debian/Ubuntu, apk add python3 make g++ on Alpine). The Dockerfile sidesteps this by installing the toolchain in the build stage regardless.
Quick start
git clone https://github.com/Squaark/squaark cd squaark npm install cp .env.example .env npm run dev
Open http://localhost:3000/admin. With no admin account yet you'll land on
a setup page to create your credentials.
The database schema is created automatically on first boot, there is no separate migration step to run.
After logging in
Installing Squaark is the short part. Setting up the shop itself - store details and currency, payments, shipping zones and tax, your catalogue, a theme, your pages and navigation, transactional email and staff accounts - is the same work whether you self-host or not, so it is covered in one place rather than twice.
Next
Setting up your shop walks through it in the order things depend on each other, and then covers each area in depth.
Scripts
| Command | Description |
|---|---|
npm run dev | Start with hot reload |
npm start | Start the built server (npm run build first) |
npm run build | Compile TypeScript to dist/ |
npm run db:migrate | Apply pending migrations manually |
npm run db:seed | Seed with sample products/collections |
Configuration
Copy .env.example to .env:
| Variable | Default | Notes |
|---|---|---|
PORT | 3000 | |
HOST | 0.0.0.0 | |
NODE_ENV | development | Set to production when deploying |
THEME_DIR | themes/linen | Active theme directory |
UPLOADS_DIR | uploads | Product image uploads |
SESSION_SECRET | (dev default) | Use a strong random value in production |
DATABASE_PATH | data/store.db | SQLite file location |
Store-level settings (name, currency, logo, email provider, etc.) are in the admin UI, not env vars.
Docker
docker compose up
Multi-stage build: compiles in a build stage, ships only compiled output and production
node_modules. A volume is mounted for /data (the database).
Note
Uploaded images under /app/uploads aren't persisted across container recreation unless you add a volume for that path too.
Project structure
src/routes/Fastify routes: storefront/, admin/, api/src/commerce/Products, collections, cart, orderssrc/theme/Handlebars engine, helpers, context builderssrc/email/Transactional email transports and templatessrc/db/migrations/SQL migration files, applied on bootthemes/linen/Bundled default themeadmin/Admin panel Handlebars templatesSee theme_engine_spec.md in the repo for the full technical spec of the theme engine.