Authentication System

Secure authentication for development and production environments

Important Updates

NEXT_PUBLIC_MOONUI_AUTH_TOKEN is now deprecated and no longer used

/api/moonui/validate-pro endpoint has been completely removed

New CLI auth server provides secure local authentication at localhost:7878

DEVELOPMENT

Development Environment

CLI authentication server for local development

terminal

$ moonui dev# Starts auth server on :7878 + Next.js dev

CLI Auth Server

Runs on localhost:7878 for secure validation

Auto Project Start

Automatically starts your Next.js dev server

Framework Support

Use --no-nextjs for Vite/CRA

PRODUCTION

Production Environment

Automatic license validation during npm install

Automatic Setup ✨

Set your license key as environment variable - the rest is handled automatically during npm install!

Set Environment Variable

MOONUI_LICENSE_KEY=moonui_xxx...# Add in Project Settings → Environment Variables
# Enable for: Production, Preview, Development

Configure Build System

Add token injection code to your framework config (see "Configure Build System" section below)

Next.js / Vite / CRA / Remix

Deploy Your App

During npm install, @moontra/moonui-pro automatically:

• Validates your license key with MoonUI API
• Saves a base64-encoded token to .moonui-license-token
• Token is read by next.config.ts and injected into app

Pro Features Unlocked! 🎉

All Pro components work automatically

Development Authentication

Enhanced CLI authentication server

The `moonui dev` Command

All-in-one development server with authentication

New in v2.13+

The moonui dev command now starts both the CLI auth server and your project's dev server automatically.

Default Usage (Next.js)

$ moonui dev# ✅ Starts CLI auth server on :7878
# ✅ Starts Next.js dev server on :3000
# ✅ Opens browser automatically

For Other Frameworks (Vite, CRA, etc.)

$ moonui dev --no-nextjs# ✅ Starts only CLI auth server on :7878
# ⚠️  You need to run your dev server separately

Auth Server Features

• Port: 7878
• Secure local validation
• 1 hour session cache
• Auto browser detection

Cache & Storage

• File: ~/.moonui/auth.encrypted
• Encrypted with device ID
• Auto-refresh on expiry
• Cross-project sharing

1. Setup Process

First-time login

$ moonui login

Opens browser for authentication

Start development

$ moonui dev

Starts auth server + project dev server

Ready to use Pro components!

Authentication handled automatically

Device Management

Device-Based Registration

Each developer device is uniquely registered using a secure fingerprint:

• Device ID: Hardware-based unique identifier
• Machine Info: OS, hostname, CPU details
• No IP tracking: Works behind VPNs and NATs

Free/Personal

device

Team

devices

Enterprise

∞

unlimited

Provider Setup

Configure MoonUIAuthProvider in your application

Required for Pro Components

MoonUIAuthProvider manages authentication state and provides context to all Pro components. It handles both development (CLI) and production (License Key) authentication automatically.

Framework-Specific Setup

Add MoonUIAuthProvider to your application's root

app/layout.tsx

import { MoonUIAuthProvider } from '@moontra/moonui-pro'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <MoonUIAuthProvider>
          {children}
        </MoonUIAuthProvider>
      </body>
    </html>
  )
}

Production Authentication

Automatic PostInstall validation system

How PostInstall Works

Automatic license validation during package installation

Automatic Process

When you run npm install on Vercel, Netlify, Docker, or any CI/CD platform, @moontra/moonui-pro automatically validates your license.

npm install triggers PostInstall

When @moontra/moonui-pro is installed, the postinstall script runs automatically

License Validation

Script reads MOONUI_LICENSE_KEY and validates with MoonUI API

Token Storage

Base64-encoded token saved to .moonui-license-token in project root

Build Time Injection

Build system reads token file and injects it into your app bundle

Runtime Pro Access

MoonUIAuthProvider reads token and unlocks Pro components

Required Environment Variable:

MOONUI_LICENSE_KEY=moonui_xxx...# Get your license key from dashboard:
# https://moonui.dev/dashboard

Cache Strategy

Cache Durations

Development (CLI)

1 hour

Production (PostInstall)

30 days

Storage Locations

Development

~/.moonui/auth.encrypted

Production Build

.moonui-license-token

Runtime

App bundle (injected)

Token Lifecycle

Production: PostInstall validates license → Token saved to file → Build system injects → Runtime access granted

Development: CLI server validates → Token cached in ~/.moonui → Components check auth server

Cache Refresh Triggers

Token automatically refreshes when:

• TTL expires (1h dev / 30 days prod)
• License key changes in environment
• npm install runs again (production)
• User explicitly logs out (development)

REQUIRED

Production Only

Configure Build System

Framework-specific configuration to inject license token at build time

Automatic Token Management

MoonUI Pro now includes build-time plugins for Next.js and Vite that automatically handle license token injection. Simply wrap your config with our plugin—no manual file reading required!

Add to next.config.ts:

import type { NextConfig } from "next";
import { withMoonUIProToken } from '@moontra/moonui-pro/next-config';

const nextConfig: NextConfig = {
  // ... your other config
};

// Wrap your config with MoonUI Pro plugin
export default withMoonUIProToken(nextConfig);

Multiple Config Wrappers

If you're using other config wrappers (Sentry, Bundle Analyzer, etc.), compose them with MoonUI Pro plugin as the innermost wrapper:

export default withSentry(
  withBundleAnalyzer(
    withMoonUIProToken(nextConfig)
  )
);

How it works

1. PostInstall validates license and creates .moonui-license-token during npm install

2. Build-time plugin automatically reads and injects the token

3. Token is available as NEXT_PUBLIC_MOONUI_PRO_TOKEN in your app

4. MoonUIAuthProvider validates the token at runtime

5. Pro components are unlocked automatically ✓

The token must exist at build time

NEXT_PUBLIC_MOONUI_PRO_TOKEN is inlined into your bundle during the build — there is no per-request runtime fallback. If npm install and the build run in separate stages or environments (Docker layers, cached node_modules, some CI setups), PostInstall may not have created the token yet — and Pro would be silently locked.

Guarantee it by regenerating the token right before every build with a prebuild script:

"scripts": {
  "prebuild": "node node_modules/@moontra/moonui-pro/scripts/postinstall.cjs",
  "build": "next build"
}

As long as MOONUI_LICENSE_KEY is set at build time, this recreates .moonui-license-token before withMoonUIProToken reads it — the same way on every platform.

Universal

v3.4.42+

Deploy Anywhere

The same two steps activate Pro on every platform — Vercel, self-hosted, or containers

One setup, every platform

There is no Vercel-only path and no VERCEL=1 flag. From v3.4.42 the token is written the same way (base64) on every system. You only ever need two things: 1) set MOONUI_LICENSE_KEY at build time, and 2) wrap your config with withMoonUIProToken.

Platform	Where to set `MOONUI_LICENSE_KEY`	Notes
Vercel	Project → Settings → Environment Variables	Works out of the box
Netlify	Site → Settings → Environment Variables	Works out of the box
Docker	`ARG` / `ENV` in the Dockerfile (build arg)	Add the `prebuild` script; keep build tools in `dependencies`
Kubernetes	In the image build (CI), not a runtime env/Secret	The token is baked at build — a runtime Secret has no effect
Dokploy / Nixpacks	Project → Environment (build variables)	Add the `prebuild` script
Bare server (PM2 / Node)	Export in the build shell / CI before `npm run build`	Same `prebuild` script

Self-hosted gotcha: keep build tools in `dependencies`

When a container or CI builds with NODE_ENV=production, npm install skips devDependencies. If tailwindcss, postcss or autoprefixer live there, the CSS pipeline is missing and the build fails. Move them to dependencies for production images.

Minimal Dockerfile (no VERCEL flag):

FROM node:22-slim
WORKDIR /app

COPY package*.json ./
# MOONUI_LICENSE_KEY as a build arg (kept out of the final image)
ARG MOONUI_LICENSE_KEY
ENV MOONUI_LICENSE_KEY=$MOONUI_LICENSE_KEY
ENV NODE_ENV=production

RUN npm install          # PostInstall validates the key + writes the token
COPY . .
RUN npm run build        # prebuild regenerates the token, withMoonUIProToken injects it
CMD ["npm", "start"]

Build with docker build --build-arg MOONUI_LICENSE_KEY=moonui_xxx -t my-app .

Troubleshooting

moonui dev not stopping with CTRL+C

If the dev server doesn't stop properly:

# Find and kill the process
$ lsof -i :7878
$ kill -9 [PID]

This issue has been fixed in v2.13.26+

Auth server not responding

Check if the auth server is running:

1. Verify port 7878 is not in use
2. Try moonui logout then moonui login
3. Clear auth cache: rm -rf ~/.moonui/auth.encrypted
4. Restart with moonui dev

PostInstall license validation failed

If Pro components remain locked in production:

1. Check Environment Variable
- ✓ Verify MOONUI_LICENSE_KEY is set on your deployment platform
- ✓ Confirm license key starts with moonui_
2. Check Build Logs
- ✓ Look for [MoonUI Pro] PostInstall messages
- ✓ Verify token file creation: ✓ Token saved to project root
3. Verify Package Version
- ✓ Ensure @moontra/moonui-pro is version 3.4.42 or later
- ⚠️ Self-hosted builds (Docker, Kubernetes, Dokploy, bare server) require 3.4.42+ — earlier versions only injected the token on Vercel/Netlify, leaving Pro silently locked elsewhere
- ✓ Run npm update @moontra/moonui-pro@latest if needed
4. Check License Status
- ✓ Verify subscription is active at moonui.dev/dashboard
- ✓ Ensure license hasn't expired

Token file not created during build

If PostInstall runs but token file isn't found:

Check Build Logs for:

[MoonUI Pro] Current working directory: ...
[MoonUI Pro] Calculated project root: ...
[MoonUI Pro] Saving token to: .../.moonui-license-token
[MoonUI Pro] ✓ Token saved to project root

If you see ❌ Error: Token file was not created, this indicates a file system permission issue on your deployment platform.

Clear all caches

To completely reset authentication:

# 1. Clear CLI auth
$ moonui logout
$ rm -rf ~/.moonui/auth.encrypted

# 2. Clear browser (in DevTools console)
localStorage.clear()
sessionStorage.clear()

# 3. Login again
$ moonui login
$ moonui dev

Migration to PostInstall System (v3.3.8+)

If you're upgrading from an older version:

1. Update Package Version
$ npm update @moontra/moonui-pro@latest
2. Update Environment Variables
- ✓ Remove old variables: NEXT_PUBLIC_MOONUI_AUTH_TOKEN, NEXT_PUBLIC_MOONUI_LICENSE_KEY
- ✓ Add new variable: MOONUI_LICENSE_KEY=moonui_xxx...
3. Configure Build System
- ✓ Add token injection code to your framework config file
- ✓ See the "Configure Build System" section above for Next.js, Vite, CRA, or Remix
4. Clean Up Old Files
- ✓ Delete /api/moonui/validate-pro if it exists
- ✓ Remove .moonui-license (old encrypted format)
5. Verify MoonUIAuthProvider
- ✓ Ensure MoonUIAuthProvider wraps your app (no changes needed)
- ✓ SubscriptionProvider is deprecated - use MoonUIAuthProvider
6. Deploy and Test
- ✓ Push changes to your repository
- ✓ Check build logs for [MoonUI Pro] ✓ Token saved
- ✓ Verify Pro components are unlocked

What's New: The new PostInstall system is fully automatic! Just set MOONUI_LICENSE_KEY and deploy. No manual token management needed.

Authentication System

Important Updates

Development Environment

Production Environment

Automatic Setup ✨

Development Authentication

The moonui dev Command

New in v2.13+

1. Setup Process

Device Management

Device-Based Registration

Provider Setup

Required for Pro Components

Framework-Specific Setup

Production Authentication

How PostInstall Works

Automatic Process

Cache Strategy

Cache Durations

Storage Locations

Token Lifecycle

Cache Refresh Triggers

Configure Build System

Automatic Token Management

Multiple Config Wrappers

How it works

The token must exist at build time

Deploy Anywhere

One setup, every platform

Self-hosted gotcha: keep build tools in dependencies

Troubleshooting

moonui dev not stopping with CTRL+C

Auth server not responding

PostInstall license validation failed

Token file not created during build

Clear all caches

Migration to PostInstall System (v3.3.8+)

The `moonui dev` Command

Self-hosted gotcha: keep build tools in `dependencies`