Installation

The steps are the same for orbix-next/ (full template) and orbix-next-starterkit/ (starter kit).

1. Copy the project

Extract the ZIP and copy orbix-next/ to your projects folder (rename it as you like). Open a terminal in that folder.

2. Install the dependencies

npm install

The design system is installed from the local folder packages/foundry-ui/ (no registry account needed).

3. Run the dev server

npm run dev

Open http://localhost:3000. Edits to components, styles and translations appear instantly (Fast Refresh).

4. Build for production

Orbix builds in two ways from the same code. Pick the one that matches your hosting.

Static export (default)

npm run build

dist/bootstrap/ now holds the whole site, prerendered: one folder per page with its index.html (dist/bootstrap/apps/kanban/index.html), 404.html, the hashed CSS and JavaScript in _next/static/ (with the font files and their licenses in _next/static/media/), the demo photos in images/, the icon sets in icon-sets/ and favicon.svg. Check it locally with npm run preview. No Node.js is needed on the server.

Node.js server (next start)

npm run build:server
npm start                  # PORT=8080 npm start for another port

The same pages, served by Next.js on Node.js 24+: use it when you add API routes, middleware, server actions or server-side data fetching to your project.

5. Run the tests (optional)

npm run build        # the build suite checks the static export
npm test

Deploy

Static hosts

Upload the contents of dist/bootstrap/. Every page is a real file (apps/kanban/index.html), so no rewrite rule is needed: a reload on any page works on every host. Unknown URLs answer 404.html when the host is told to use it.

Netlify

Build command npm run build, publish directory dist/bootstrap. Netlify serves 404.html automatically.

Vercel

Static: framework preset "Other", build command npm run build, output directory dist/bootstrap. Server: import the project with the "Next.js" preset, build command next build and the environment variable ORBIX_OUTPUT=server.

Nginx

server {
  listen 80;
  server_name admin.example.com;
  root /var/www/orbix;            # contents of dist/bootstrap
  index index.html;

  location / {
    try_files $uri $uri/ =404;
  }
  error_page 404 /404.html;

  location /_next/static/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }
}

Apache

Works without configuration (folders answer their index.html; Apache adds the trailing slash). For the 404 page, in the virtual host or an .htaccess file next to index.html:

ErrorDocument 404 /404.html

IIS, S3 + CloudFront, GitHub Pages, Cloudflare Pages

Upload the folder; set index.html as the default document and 404.html as the error document.

Sub-folder

To serve the site from a sub-folder (for example https://example.com/admin/), build with the base path:

ORBIX_BASE=/admin npm run build          # Windows PowerShell: $env:ORBIX_BASE="/admin"; npm run build

Upload dist/bootstrap into the admin/ folder and point the 404 page to /admin/404.html (Nginx: error_page 404 /admin/404.html;). Every link, image and route follows the base path (Next.js basePath). Preview it locally with ORBIX_BASE=/admin npm run preview (http://localhost:4173/admin/).

Node.js server

npm ci
npm run build:server
npm start

Keep it running with a process manager (pm2 start npm --name orbix -- start) and put Nginx in front of it (proxy_pass http://127.0.0.1:3000;).

Docker

Server mode:

FROM node:24-alpine
WORKDIR /app
COPY . .
RUN npm ci && npm run build:server
ENV NODE_ENV=production PORT=3000
EXPOSE 3000
CMD ["npm", "start"]

Static export: build with node:24 (npm ci && npm run build), then copy dist/bootstrap into an nginx:alpine image with the configuration above.

Troubleshooting