Instant Everything
Nounjs CLI is built for speed. Bun-powered builds complete in milliseconds. One command deploys your app to yourapp.nounjs.app in seconds.
Installation
# Global installation
npm install -g @noundryfx/nounjs
# Or use bunx/npx without installing
bunx @noundryfx/nounjs <command>
npx @noundryfx/nounjs <command>
Recommended: Use Bun for faster execution: bunx @noundryfx/nounjs <command>
Commands Overview
| Command | Description |
|---|---|
| create | Create a new project |
| dev | Build and start dev server with hot reload |
| build | Build CSS and JS for production |
| bundle / prod | Full production build |
| publish | Build and deploy to nounjs.app |
| compile | Compile .noun files to JS |
| generate / g | Generate components and pages |
| scaffold | Generate complete UI from OpenAPI spec |
| add | Add UI components |
| validate | Validate templates |
| doctor | Diagnose project issues |
| refresh / upgrade | Update Nounjs core files to latest version |
noun create
Create a new Nounjs project with complete scaffolding.
# Create with default Tailwind styling
noun create my-app
# Create with Basecoat UI styling
noun create my-app --basecoat
# Explicit styling options
noun create my-app --style tailwind
noun create my-app --style basecoat
# Include sample components
noun create my-app --sample
Options
| Option | Description |
|---|---|
--style <name> | Choose styling: tailwind (default) or basecoat |
--tailwind | Shorthand for --style tailwind |
--basecoat | Shorthand for --style basecoat |
--sample | Include sample components |
noun dev
Build the project and start a development server with hot reload.
noun dev # Start on port 3000
noun dev 8080 # Custom port
noun dev --no-banner # Minimal banner output
_ _ _ ____ | \ | | ___ _ _ _ __ | / ___| | \| |/ _ \| | | | '_ \ _ | \___ \ | |\ | (_) | |_| | | | | |_| |___) | |_| \_|\___/ \__,_|_| |_|\___/|____/ v0.9.31 info Starting development server... done Compiled 10 components in 28ms done dist/styles.css (57.7kb) in 1067ms done Initial build complete in 1217ms
Hot reload watches for changes in CSS, .noun files, and app.js, automatically refreshing the browser.
noun build / noun prod
Build CSS and JavaScript for production.
# Standard build
noun build
noun build --verbose # Show detailed output
# Full production build (recommended)
noun prod # Alias for noun bundle
noun bundle --no-banner
Production Build Steps
- Copy latest Nounjs runtime (noun.esm.js, router.esm.js) to dist/
- Compile .noun files from src/pages/ to src/compiled/
- Build and minify Tailwind CSS to dist/styles.css
- Bundle and minify JavaScript with source maps to dist/app.bundle.js
noun publish
Build and deploy your app to nounjs.app hosting. One command. Live in seconds.
# Deploy with auto-detected app name
noun publish
# Deploy with specific app name
noun publish my-app
# Preview deployment (7-day expiration)
noun publish my-app --preview
# PR-specific preview
noun publish my-app --pr 123
# Dry run (preview what would be uploaded)
noun publish --dry-run
# Skip build step
noun publish --skip-build
Your app is live at https://my-app.nounjs.app
noun publish.
Authentication
Set your token via environment variable, config file, or CLI argument:
# Environment variable
export NOUN_TOKEN=your-token
# Config file (~/.nounrc)
{"token": "your-token"}
# CLI argument
noun publish --token your-token
noun generate
Generate components and pages with templates.
# Generate a component
noun g component Button
# Generate pages with different types
noun g page Dashboard # Basic page
noun g page Users list # List page with search/table
noun g page Products grid # NounTable data grid
noun g page UserEdit form # Create/edit form
noun g page UserDetail detail # Detail view
noun g page Login login # Login page
Page Types
| Type | Description |
|---|---|
basic | Simple page with header and content (default) |
list | Data list with search and table |
grid | NounTable data grid with inline editing |
form | Create/edit form with validation |
detail | Detail view page |
login | Authentication login page |
noun scaffold
Generate a complete Nounjs application from an OpenAPI/Swagger specification. Point at any API, get a full working UI.
Transform any OpenAPI spec into a fully functional admin dashboard with list, detail, and form pages for every resource. Perfect for rapid prototyping or building internal tools.
# Generate from a URL
noun scaffold https://api.example.com/openapi.json
# Generate from a local file
noun scaffold ./swagger.json
# With custom output directory and app name
noun scaffold https://api.example.com/openapi.json --output ./my-dashboard --name "Admin Panel"
# Use Basecoat styling instead of Tailwind
noun scaffold ./api-spec.json --basecoat
# Force overwrite existing files
noun scaffold ./swagger.json --force
Options
| Option | Description |
|---|---|
--output, -o <dir> | Output directory (default: current directory) |
--name, -n <name> | App name (default: from API title in spec) |
--style, -s <style> | Styling system: 'tailwind' (default) or 'basecoat' |
--basecoat | Shorthand for --style basecoat |
--skip-install | Don't run bun install after scaffolding |
--skip-compile | Don't compile .noun files after generation |
--force, -f | Overwrite existing files |
What Gets Generated
API Client
src/api/client.js- Full API client with all endpointssrc/api/types.js- JSDoc type definitions from schemassrc/api/auth.js- Auth store with token management
Layout & Dashboard
src/pages/layout.noun- App shell with sidebar + logoutsrc/pages/dashboard.noun- Overview with resource cardssrc/pages/login.noun- Login page (if auth defined)
Resource Pages
{resource}-list.noun- Data table with search & pagination{resource}-detail.noun- Single item detail view{resource}-form.noun- Create/edit form with validation
Project Files
app.js- Entry point with router + auth guardsindex.html- HTML templatenoun.config.json- Project configuration
Authentication Support
Scaffold automatically detects securitySchemes in your OpenAPI spec and generates appropriate authentication UI and logic.
Supported Auth Types
- OAuth2 - Authorization Code, Implicit, Password, Client Credentials
- HTTP Basic - Username/password authentication
- HTTP Bearer - JWT or token-based auth
- API Key - Header, query, or cookie-based keys
Generated Features
- Login page tailored to auth type
- Auth store with token persistence
- Route guards for protected pages
- Logout button in layout header
- Token refresh support (OAuth2)
How It Works
-
1
Parse OpenAPI Spec - Fetches and parses the OpenAPI/Swagger JSON from a URL or local file. Resolves $ref references and extracts API metadata.
-
2
Discover Resources - Analyzes paths to identify REST resources (e.g., /products, /users) and their CRUD operations (list, read, create, update, delete).
-
3
Extract Schemas - Pulls schema definitions to understand data models, property types, validation rules, and relationships.
-
4
Generate Code - Creates API client methods, type definitions, and .noun pages tailored to each resource's schema and available operations.
-
5
Compile & Configure - Compiles .noun files to JavaScript and sets up routing for all generated pages.
Common OpenAPI Endpoints
| Framework | Typical Endpoint |
|---|---|
| .NET / ASP.NET | /openapi/v1.json, /swagger/v1/swagger.json |
| Node.js / Express | /api-docs, /swagger.json |
| FastAPI (Python) | /openapi.json |
| Spring Boot (Java) | /v3/api-docs |
| Rails / Grape | /swagger_doc.json |
Example: Pet Store API
# Generate a dashboard for the Swagger Pet Store demo API
noun scaffold https://petstore.swagger.io/v2/swagger.json --name "Pet Store Admin"
# Navigate to the project
cd pet-store-admin
# Install dependencies and start
bun install && noun dev
The generated app makes requests directly to your API. If your API runs on a different domain, ensure CORS is properly configured to allow requests from your development server.
noun compile
Compile .noun single-file components to JavaScript.
# Compile once
noun compile
# Watch mode
noun compile --watch
# Verbose output with timing
noun compile --verbose
# Custom paths
noun compile --src src/components --out dist/components
noun refresh
Update Nounjs core files in your project when a new version of the CLI is available.
# Check and update to latest version
noun refresh
# Force refresh even if versions match
noun refresh --force
# Alias: upgrade
noun upgrade
When to use: Run noun refresh after updating the Nounjs CLI to get the latest framework improvements in your existing projects.
What Gets Updated
build/noun.esm.js- Core framework module (local build artifacts)build/router.esm.js- Router modulenoun.config.json- Version tracking updated
Options
| Option | Description |
|---|---|
--force, -f | Force refresh even if project is already up to date |
Configuration
Project configuration in noun.config.json:
{
"nounVersion": "0.9.19",
"style": "basecoat",
"compile": {
"input": "src/pages",
"output": "src/compiled"
},
"bundle": {
"entry": "app.js",
"output": "dist/app.js"
}
}
| Option | Description |
|---|---|
nounVersion | Nounjs version used to create/update the project (used by noun refresh) |
style | Styling system: tailwind or basecoat |
compile.input | Source directory for .noun files |
compile.output | Output directory for compiled JS |
bundle.entry | JavaScript entry point |
bundle.output | Bundled output file |