nuxt-dashboard-template-01 — Nuxt 后台模板

SHA-256: 3de4cd2e05176545a8169ce12ae2c5c62f80caf8a073c97cd7041794b5eae805

2026-10-13T08:56:54.123Z

# Nuxt Dashboard Template

Production-ready **Nuxt 4** dashboard starter with TypeScript, Tailwind CSS, Pinia, `@nuxtjs/i18n`, and Clean Layered Architecture.

**Live template preview:** [https://template.teristimewa.com/nuxt-dashboard-template-01](https://template.teristimewa.com/nuxt-dashboard-template-01) .

<a href="https://template.teristimewa.com/nuxt-dashboard-template-01">
  <img src="./public/og-image.jpg" alt="Teristimewa Dashboard" width="240" />
</a>

Choose Language / Pilih Bahasa:

- English (this document)
- [Bahasa Indonesia](./README.id.md)

> **Need more detail?** Architecture, Pinia patterns, API wiring, manual page creation, and full code walkthroughs → [DOCUMENTATION.md](./DOCUMENTATION.md) · [DOCUMENTATION.id.md](./DOCUMENTATION.id.md)

## What you get

- **Auth** — login/register with route guards
- **Features** — Dashboard, Users (full CRUD), Orders, Inventory (tutorial example), Settings
- **i18n** — English & Indonesian via `locales/` and `useLocale()`
- **Scaffolding** — `make generate` for a new app, `make feature` for menu + page
- **In-app docs** — step-by-step Overview and Tutorial (development mode only)
- **Component catalog** — Storybook-style UI gallery at `/components` (development mode only)
- **Static SPA deploy** — `ssr: false` in `nuxt.config.ts`; production output is `.output/public/` (see [Deployment](./DOCUMENTATION.md#18-deployment))

---

## Prerequisites

Install these **before** cloning or running the app. Versions match [package.json](./package.json) (Volta-pinned).

**Node + pnpm toolchain:** full setup for macOS / Linux / Windows (with or without Volta) → [VOLTA.md](./VOLTA.md) · [VOLTA.id.md](./VOLTA.id.md). Same pinned versions either way: Node **22.23.1**, pnpm **11.17.0**.

> **Already have everything?** If `node`, `pnpm`, and `git` work in your terminal, skip to [Quick Start](#quick-start). You only need `make` (optional shortcuts) and `rsync` (only for `make generate`).

| Tool        | Version                    | Required    | Used for                                               |
| ----------- | -------------------------- | ----------- | ------------------------------------------------------ |
| **Node.js** | 22.x (22.23.1 recommended) | Yes         | Runtime & build                                        |
| **pnpm**    | 11.x (11.17.0 recommended) | Yes*        | Install dependencies & run scripts                     |
| **Git**     | any recent                 | Recommended | Clone repo, `make generate` init                       |
| **make**    | any (GNU Make)             | Optional    | Makefile shortcuts (`make dev`, etc.)                  |
| **rsync**   | any                        | Optional    | `make generate` only (Mac/Linux usually pre-installed) |

\* npm works as a fallback (`npm install`, `npm run dev`) but this project is tested with **pnpm**.

pnpm 11 uses `pnpm-workspace.yaml` for install policy (`allowBuilds` for native deps such as `esbuild`). Keep `packageManager` / Volta / `.nvmrc` aligned when changing versions.

### Verify installation

```bash
node --version    # expect v22.x (e.g. v22.23.1)
pnpm --version    # expect 11.x (e.g. 11.17.0)
git --version     # any recent version
make --version    # optional — skip if you use pnpm scripts directly
rsync --version   # optional — only needed for make generate
```

---

### Install from scratch

Pick your operating system. Follow the steps **in order** if nothing is installed yet.

| OS          | Section                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------- |
| **macOS**   | [macOS](#macos)                                                                                               |
| **Linux**   | [Linux (Debian / Ubuntu)](#linux-debian--ubuntu) · [Fedora / RHEL](#linux-fedora--rhel) · [Arch](#linux-arch) |
| **Windows** | [WSL (recommended)](#windows-wsl-recommended) · [Native PowerShell](#windows-native-powershell)               |

#### macOS

```bash
# 1. Git + make (Xcode Command Line Tools — includes both)
xcode-select --install

# 2. Homebrew (skip if already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 3. Node.js 22 + pnpm (pick one method)

# Option A — Homebrew (simple)
brew install node pnpm

# Option B - Volta (exact pinned versions, recommended)
# Full per-shell steps: VOLTA.md
curl https://get.volta.sh | bash
# Restart terminal, enable VOLTA_FEATURE_PNPM (see VOLTA.md), then:
volta install [email protected] [email protected]

# 4. rsync — included with macOS (no install needed)
# 5. make — included with Xcode CLT above

# Verify
node --version && pnpm --version && git --version && make --version && rsync --version
```

#### Linux (Debian / Ubuntu)

```bash
sudo apt update
sudo apt install -y git
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g [email protected]
sudo apt install -y build-essential rsync

# Optional: Volta for exact versions (see VOLTA.md)
curl https://get.volta.sh | bash
volta install [email protected] [email protected]

node --version && pnpm --version && git --version && make --version && rsync --version
```

#### Linux (Fedora / RHEL)

```bash
sudo dnf install -y git make rsync
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs
npm install -g [email protected]

node --version && pnpm --version && git --version && make --version && rsync --version
```

#### Linux (Arch)

```bash
sudo pacman -S --needed git make rsync nodejs npm
npm install -g [email protected]

node --version && pnpm --version && git --version && make --version && rsync --version
```

#### Windows (WSL — recommended)

Full support for `make`, `rsync`, and `make generate`. Install WSL, then use the Linux steps inside Ubuntu.

```powershell
wsl --install
# Restart PC if prompted, then open "Ubuntu" from Start menu
```

Inside the **Ubuntu** terminal, follow [Linux (Debian / Ubuntu)](#linux-debian--ubuntu) above.

```bash
git clone https://github.com/KutuGondrong/nuxt-dashboard-template-01.git
cd nuxt-dashboard-template-01
pnpm install
make dev
```

#### Windows (native — PowerShell)

Works for daily dev (`pnpm dev`). For `make generate`, use [WSL](#windows-wsl-recommended) (needs `rsync`).

```powershell
winget install Git.Git
winget install OpenJS.NodeJS.LTS
npm install -g [email protected]
winget install GnuWin32.Make   # optional — or use pnpm scripts

node --version
pnpm --version
git --version
make --version
```

| Windows setup          | make | rsync | make generate                                     |
| ---------------------- | ---- | ----- | ------------------------------------------------- |
| **WSL + Ubuntu**       | yes  | yes   | yes                                               |
| **Native + pnpm only** | no   | no    | use WSL or `node scripts/generate-app.mjs` in WSL |
| **Native + make**      | yes  | no    | use WSL for rsync                                 |

---

## Quick Start

### 1. Clone the template

```bash
git clone https://github.com/KutuGondrong/nuxt-dashboard-template-01.git
cd nuxt-dashboard-template-01
```

### 2. Install & run

```bash
pnpm install
make dev
```

Open **http://localhost:3000**. Demo login: `[email protected]` / `password123`

### 3. Scaffold your own app (optional)

From inside the cloned template:

```bash
make generate name=my-new-app
cd ../my-new-app
rm -rf ../nuxt-dashboard-template-01
pnpm install
make dev
```

Default output is `../my-new-app` (sibling folder, outside the template). Custom path: `make generate name=my-app out=~/projects/my-app`.

---

## Documentation & Components (development mode)

When you run `make dev`, the sidebar shows **Documentation** and **Components** with a DEV badge (`NUXT_PUBLIC_SHOW_DEV_FEATURES=false` to hide). Those pages are landings that open the published Documentation and Components sites in a new tab.

Interactive step-by-step UI (Overview + Tutorial tabs) is documented in [DOCUMENTATION.md § In-app Documentation](./DOCUMENTATION.md#14-in-app-documentation-overview--tutorial).

---

## Scaffolding

### `make generate` — new app from template

```bash
make generate name=my-new-app
make generate name=my-app out=~/projects/my-app
```

Creates a copy outside this repo, updates `package.json` name, and runs `git init` in the output folder.

### `make feature` — menu + page

```bash
make feature name=inventory label="Inventory" label-id="Inventaris"
make feature name=reports scope=store label="Reports" label-id="Laporan"
make feature name=alerts scope=page label="Alerts" label-id="Peringatan"
```

| Parameter  | Required    | Description                                                                                          |
| ---------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| `name`     | Yes         | Feature key: `features/<name>/`, route `/<name>`, locale key `nav.<name>`. Use lowercase kebab-case. |
| `label`    | Recommended | English sidebar label → `locales/en.json` (`nav.*`)                                                  |
| `label-id` | Recommended | Indonesian sidebar label → `locales/id.json` (`nav.*`). Falls back to `label` if omitted.            |
| `scope`    | No          | `full` (default), `store`, or `page` (alias: `empty`)                                                |

| Scope   | Generated                                                   |
| ------- | ----------------------------------------------------------- |
| `full`  | page + table + Pinia store + usecase (mock data in usecase) |
| `store` | page + table + Pinia store (mock inline, no usecase file)   |
| `page`  | empty page + menu/route/locale wiring only                  |

Always updated: `pages/<name>/index.vue` (via generate), `layouts/sidebar/featureMenuItemsGenerate.ts` / `featureMenuItems.ts`, `locales/en.json` + `id.json`, and `config/generatedPages.ts`.

For manual wiring, mock vs real API, and full code samples, see [DOCUMENTATION.md](./DOCUMENTATION.md#16-create-a-new-page--manual-walkthrough) and the **Tutorial** tab in the app.

---

## Without Make

If you **don't have `make`**, use **pnpm scripts** directly:

| Instead of                         | Run                         |
| ---------------------------------- | --------------------------- |
| `make dev`                         | `pnpm dev`                  |
| `make build`                       | `pnpm format && pnpm build` |
| `make lint`                        | `pnpm lint`                 |
| `make format`                      | `pnpm format`               |
| `make preview`                     | `pnpm preview`              |
| `make feature name=X label="Name"` | see below                   |
| `make generate name=X`             | see below                   |

**Minimal run (no make at all):**

```bash
pnpm install
pnpm dev
```

### Scaffolding without Make

```bash
# label     = English sidebar text (en.json)
# label-id  = Indonesian sidebar text (id.json)
node scripts/generate-feature.mjs --name=orders --label="Orders" --label-id="Pesanan"
node scripts/generate-feature.mjs --name=reports --scope=store --label="Reports" --label-id="Laporan"
node scripts/generate-feature.mjs --name=inventory --scope=page --label="Inventory" --label-id="Inventaris"

# Clone this template outside the current folder (needs rsync; use WSL on Windows)
node scripts/generate-app.mjs --name=my-app
node scripts/generate-app.mjs --name=my-app --out=~/projects/my-app
```

The in-app Tutorial header toggle switches between `make` and `node & pnpm` command modes.

---

## Commands (Makefile)

| Command                                                                                | Description                                                               |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `make dev`                                                                             | Start Nuxt dev server (Documentation & Components visible with DEV badge) |
| `make build`                                                                           | Format, type-check, and production build (dev routes stripped)            |
| `make lint`                                                                            | ESLint + TypeScript check (no file writes)                                |
| `make format`                                                                          | Prettier + ESLint auto-fix                                                |
| `make preview`                                                                         | Serve production build locally (next free port if busy)                   |
| `make clean`                                                                           | Remove `.output`, `.nuxt`, `.turbo`                                       |
| `make generate name=my-app [out=PATH]`                                                 | Scaffold micro-app outside this template (default: `../my-app`)           |
| `make feature name=X [scope=full\|store\|page] label="English" [label-id="Indonesia"]` | Scaffold menu + page (bilingual sidebar labels)                           |
| `make test-feature`                                                                    | Run generate-feature script tests                                         |

---

## Project structure

Layered layout under the project root (`pages/`, `layouts/`, `features/<name>/`, plus `config`, `locales`, `models`, `datasource`, `components`). Full tree and layer rules → [DOCUMENTATION.md § Project Structure](./DOCUMENTATION.md#8-project-structure).

---

## Environment

| Variable                           | Purpose                                      |
| ---------------------------------- | -------------------------------------------- |
| `NUXT_PUBLIC_API_BASE_URL`         | Backend base URL                             |
| `NUXT_PUBLIC_SHOW_DEV_FEATURES`    | Show or hide Documentation & Components menu |
| `NUXT_PUBLIC_ENABLE_SCROLL_TO_TOP` | Scroll-to-top button (default: true)         |

Set `previewUrl` in `config/external-links.json` (or `NUXT_PUBLIC_OG_SITE_URL` in `.env.production`) to your deployed app URL so link previews use `public/og-image.jpg`.

See `.env` for defaults. Dev vs production overrides and deployment → [DOCUMENTATION.md § Deployment](./DOCUMENTATION.md#18-deployment).

This template ships as a **static SPA** (`ssr: false`). To run with SSR / a Node server instead, change that flag in `nuxt.config.ts` and adjust your host accordingly (details in the Deployment section).

---

## Further reading

| Doc                                          | Content                                                                                                     |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [DOCUMENTATION.md](./DOCUMENTATION.md)       | **Deep developer guide** (English): bootstrap, Pinia, routing, data layer, manual page creation, API wiring |
| [DOCUMENTATION.id.md](./DOCUMENTATION.id.md) | Panduan developer mendalam (Bahasa Indonesia)                                                               |
| [VOLTA.md](./VOLTA.md)                       | Node + pnpm toolchain setup (Volta, per OS/shell)                                                           |
| [VOLTA.id.md](./VOLTA.id.md)                 | Setup toolchain Node + pnpm (Volta, per OS/shell)                                                           |
| [README.id.md](./README.id.md)               | This overview in Bahasa Indonesia                                                                           |

In-app **Documentation** (DEV badge) during `make dev` links to the published interactive guide.

---

## Stack

- Vue 3 + TypeScript
- Nuxt 4
- Tailwind CSS 3
- Pinia
- Axios with interceptors
- Volta-pinned Node 22.23.1 / pnpm 11.17.0