Setup & Configuration

This guide covers everything you need to get the admin dashboard running locally, configure it for your store, and deploy it to production.

Prerequisites

Node.js 18 or later

A Hanzo account with API credentials (hanzo.ai)

Access to your Hanzo Commerce backend

Installation

# Clone the admin dashboard
git clone https://github.com/hanzoai/commerce-admin.git
cd commerce-admin

# Install dependencies
npm install

# Start the dev server
npm run dev

The dashboard will be available at http://localhost:5173.

Environment Variables

Create a .env file in the project root:

# Required
VITE_HANZO_API_URL=https://api.hanzo.ai/v1
VITE_HANZO_API_KEY=your_publishable_api_key

# Authentication (hanzo.id)
VITE_HANZO_AUTH_URL=https://id.hanzo.ai
VITE_HANZO_CLIENT_ID=your_client_id
VITE_HANZO_REDIRECT_URI=http://localhost:5173/callback

# Optional
VITE_HANZO_CDN_URL=https://cdn.hanzo.ai
VITE_SENTRY_DSN=your_sentry_dsn
VITE_ANALYTICS_ID=your_analytics_id

Variable	Required	Description
`VITE_HANZO_API_URL`	Yes	Commerce API base URL
`VITE_HANZO_API_KEY`	Yes	Publishable API key for your store
`VITE_HANZO_AUTH_URL`	Yes	hanzo.id authentication endpoint
`VITE_HANZO_CLIENT_ID`	Yes	OAuth2 client ID from hanzo.id
`VITE_HANZO_REDIRECT_URI`	Yes	OAuth2 callback URL
`VITE_HANZO_CDN_URL`	No	CDN prefix for media assets
`VITE_SENTRY_DSN`	No	Sentry DSN for error tracking

Authentication Setup

The admin dashboard uses hanzo.id for authentication via the OAuth2 PKCE flow:

Set the redirect URI to your dashboard URL (e.g. http://localhost:5173/callback)

Copy the client ID into VITE_HANZO_CLIENT_ID

Assign admin roles to your team members in the hanzo.id console

// Authentication is handled automatically by the SDK
import { HanzoSDK } from '@hanzo/sdk'

const sdk = new HanzoSDK({
  baseUrl: import.meta.env.VITE_HANZO_API_URL,
  apiKey: import.meta.env.VITE_HANZO_API_KEY,
})

// Login redirects to hanzo.id
await sdk.auth.login({ returnTo: '/dashboard' })

// After callback, the session is persisted
const user = await sdk.auth.me()

Custom Branding

Override the default theme by editing tailwind.config.ts:

export default {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f0f9ff',
          500: '#3b82f6',
          900: '#1e3a5f',
        },
      },
    },
  },
}

You can also replace the logo and favicon in the public/ directory:

public/logo.svg -- sidebar and login page logo

public/favicon.ico -- browser tab icon

public/og-image.png -- social sharing preview image

Building for Production

# Build the optimized bundle
npm run build

# Preview the production build locally
npm run preview

The output is written to dist/ as a static SPA.

Deployment

Vercel (Recommended)

npm install -g vercel
vercel --prod

Set environment variables in the Vercel dashboard under Settings > Environment Variables.

Docker

FROM node:18-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

docker build -t commerce-admin .
docker run -p 8080:80 commerce-admin

Static Hosting

Upload the contents of dist/ to any static host (S3 + CloudFront, Netlify, Cloudflare Pages). Ensure all routes fall back to index.html for client-side routing.

For production deployments, always set VITE_HANZO_API_URL to your production API endpoint and use a production API key with appropriate scopes.

Setup & Configuration

On this page