JCC Express

Installation

This guide walks you through installing and running a JCC Express MVC application. JCC Express is a Laravel-inspired framework on top of Express.js and TypeScript, tuned for the Bun runtime. By the end, you should have dependencies installed, environment configured, the database ready, and the dev server responding in the browser.

What you are installing

You will set up four pieces:

  • Bun — JavaScript runtime and package manager. The stack expects Bun for dev and many workflows.
  • Application code — Routes, controllers, models, and views, from jcc-express-starter or a cloned repo.
  • Database — MySQL, PostgreSQL, or SQLite. Data goes through JCC Eloquent (Knex), or optionally Sequelize/Mongoose.
  • .env — Local config: ports, DB credentials, secrets. Do not commit real secrets.

1. Prerequisites

1.1 Bun (required)

Install Bun (official installer):

Bash

Restart your terminal, then check:

Bash

You should see a version number (for example 1.2.x).

1.2 Database

Pick one:

  • MySQL or MariaDB — common default in examples below
  • PostgreSQL — supported via DB_CONNECTION
  • SQLite — fine for local experiments; set connection accordingly in .env

Create an empty database (example name: jcc_express) and a user with rights to create tables. You will plug the credentials into .env when you configure the environment (see below).

1.3 Git (recommended)

Use Git to clone projects or manage your own repo. Optional but standard for real projects.

2. Get the application code

You can start in either of these ways.

Option A — New project from the starter (recommended for a fresh app)

Run the starter from your terminal using either npx (npm) or bunx (Bun)—both invoke the same tool:

Bash
  1. Interactive frontend choice — The CLI opens a prompt: “Select your preferred frontend.” Use ↑ and ↓ to move, then Enter to confirm. Typical options:
  • Inertia + React
  • Inertia + React + TypeScript
  • Inertia + Vue
  • Inertia + Vue + TypeScript
  1. What happens next — After you choose a stack, the starter scaffolds the project (folders such as app/, routes/, database/, bootstrap/, frontend wiring for your choice, package.json scripts, etc.), then installs packages. If that finishes without errors, a .env file is created for you (often with .env.example alongside for reference). You do not need to copy .env by hand for a successful starter run.
  1. Enter the project
Bash

You usually do not need another install step. If node_modules is missing or the installer reported a failure, run:

Bash
If the starter used npm for install, the app still runs with Bun; bun install afterward is fine if you want a single toolchain.

Option B — Clone an existing repository

If you already have a JCC Express project (for example this framework’s example app):

Bash

3. Environment file

3.1 .env file

If you used the starter (Option A): .env is already created. Open it in your editor and update values for your machine.

If you cloned a repo (Option B): create .env from the example if the repo does not ship a committed .env (most teams ignore it in Git):

Bash

The framework reads these values at boot (often via dotenv and app/Config). The important machine-specific edits are usually the real database credentials and other secrets (host, password, session secret, etc.). .env.example in your repo lists every key and is the source of truth for names and optional features.

3.2 Generate JWT_SECRET

JWT-based auth expects a strong JWT_SECRET in .env. Generate and write it automatically from the project root (default key name is JWT_SECRET):

Bash

Re-run this anytime you need to rotate the secret. To print a value without writing .env, use bun artisanNode key:generate show. For flags and arguments, run bun artisanNode key:generate --help.

Example (adjust keys to match your .env.example):

env

OAuth / mail / other features — only fill these when you need them (Socialite, SMTP, etc.). Your .env.example usually documents the keys.

4. Dependencies (usually already done)

If you used npx jcc-express-starter, dependencies are normally installed as part of that command—nothing extra here.

If you cloned a repo (Option B), run once from the project root:

Bash

Re-run bun install whenever package.json changes (new packages or lockfile updates).

5. Database migrations

JCC Eloquent migrations live under database/migrations/. The CLI command (from the project root) is typically:

Bash

What this does:

  1. Ensures a migrations table exists (if the framework uses that pattern).
  2. Runs each pending migration file in order to create or alter tables.

If migrate fails:

  • Confirm MySQL/Postgres is running and the database from .env exists.
  • Check DB_CONNECTION matches your driver (mysql2, postgres, better-sqlite3, etc.).
  • Read the error message: wrong password, unknown database, and SQL syntax issues are the most common.

6. (Optional) Seed sample data

Some projects ship seeders under database/seeders/. To run all seeders:

Bash

To run one seeder class by name:

Bash

If db:seed fails on path aliases like @/Model/..., run only the seeders that load cleanly, or fix imports — your project docs may describe this.

7. Run the application

Scripts are defined in package.json. bun run <script> and npm run <script> both work the same way—use whichever matches your setup.

For a typical Inertia + Vite app, use two terminals in the project root. Start the asset bundler first, then the server.

7.1 Frontend assets first (Vite)

In the first terminal:

Bash

or:

Bash

This starts Vite in watch mode (React/Vue, Tailwind, hot reload, etc.). Let it keep running.

7.2 API / server (second terminal)

In a second terminal, from the same project root:

Bash

or:

Bash

This usually runs bun --watch server.ts (when using Bun) or the dev script from package.json, which boots Express and your bootstrap pipeline.

7.3 Open the app

In the browser, visit:

text

Use the PORT from .env (e.g. http://localhost:5500). You should see your welcome route or home page.

8. Command-line interface (Artisan-style)

The ArtisanNode CLI is artisanNode. From the application root (where server.ts and bootstrap/ live):

Bash

Use bun artisanNode list or bun artisanNode help [command] to see commands (migrate, key:generate, make:controller, make:model, db:seed, etc.).

9. Verify installation (quick checklist)

  • [ ] bun --version prints a version
  • [ ] Dependencies are present (starter did install, or you ran bun install after a clone)
  • [ ] .env exists and is filled in for your machine (starter projects already have the file; cloned repos may need cp .env.example .env)
  • [ ] bun artisanNode key:generate has set JWT_SECRET (required for JWT auth)
  • [ ] bun artisanNode migrate completed (or you intentionally skip DB for now)
  • [ ] watch then dev both run without crashing (bun run / npm run as you prefer)
  • [ ] Browser loads http://localhost:<PORT>

10. Common problems

  • Port already in use — Change PORT in .env or stop the other process using that port.
  • Cannot connect to database — Check host, port, user, password, and database name; firewall; whether MySQL/Postgres is running.
  • Migration SQL errors — Driver version and SQL compatibility; try a clean DB or fix migration state (see project docs).
  • Module not found / @/ alias — tsconfig.json paths must include the project root; some CLIs need the app bootstrap to resolve aliases.
  • Session / CSRF / login oddities — APP_URL, cookie settings, HTTPS in production, SESSION_SECRET (or equivalent).
  • JWT / token errors (401, invalid signature) — Run bun artisanNode key:generate so JWT_SECRET in .env is set and stable; restart dev after changing it.
  • Configuration.md — .env, app/Config, and how values are loaded at runtime
  • Directory-structure.md — Project folders and what each is for
  • Frontend.md — Why watch runs before dev (Vite + Inertia)
  • Deployment.md — Production .env, builds, migrations, and process management
  • docs/docs-for-dev.md — broad framework guide (routing, Eloquent, validation, queues, etc.)
  • docs/getting-started.md — shorter orientation
  • README.md (project root) — feature overview and quick start
  • documentation-design (repo pointer file) — if your app includes the documentation CMS tables

Summary

  1. Install Bun and a database.
  2. New app: run npx jcc-express-starter my-app or bunx jcc-express-starter my-app, pick a frontend in the prompt, wait for scaffold + install; if it succeeds, .env is created. Then cd my-app. Existing repo: git clone then bun install.
  3. Edit .env (starter creates it; clones often use cp .env.example .env). Set app URL, port, database, and other values for your machine.
  4. Run bun artisanNode key:generate so JWT_SECRET is set for JWT auth.
  5. Run bun artisanNode migrate (and optionally db:seed).
  6. Run watch first, then dev (e.g. bun run watch then bun run dev, or the same with npm run—both work).
  7. Open http://localhost:<PORT> in the browser.

You now have a working local installation of JCC Express MVC.