Skip to content

Commit a26fce1

Browse files
davidstackiodavidstackio
committed
ai: add agents.md
1 parent d44227e commit a26fce1

1 file changed

Lines changed: 99 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Nuxtify App Context
2+
3+
This instructions file outlines the codebase structure, development standards, architectural paradigms, and commands for `@nuxtify/app` to maintain high-quality context for AI agents and development team.
4+
5+
## Project Overview
6+
7+
`@nuxtify/app` is a comprehensive Nuxt module that provides a single-page application (SPA) skeleton powered by **Nuxt 4**, **Vuetify** (integrated via `@nuxtify/core`), and **Firebase** (via `nuxt-vuefire`). It includes built-in layouts, pages, components, and utility composables to enable rapid SaaS and AI application prototyping.
8+
9+
### Core Stack
10+
- **Framework:** Nuxt 4
11+
- **UI Framework:** Vuetify (integrated via `@nuxtify/core`)
12+
- **Backend/Auth Integration:** Firebase and Vuefire (`nuxt-vuefire`)
13+
- **Testing:** Vitest and `@nuxt/test-utils`
14+
- **Type Checking:** TypeScript and `vue-tsc`
15+
16+
---
17+
18+
## Architectural Paradigms & Codebase Structure
19+
20+
The codebase is organized into two main parts: the Nuxt module source (`src/`) and a demo playground for development and testing (`playground/`).
21+
22+
```
23+
nuxtify-app/
24+
├── src/ # Module source code
25+
│ ├── module.ts # Module definition and setup entrypoint
26+
│ ├── types/ # TypeScript type definitions (module options, etc.)
27+
│ └── runtime/ # Code injected into the host Nuxt application
28+
│ ├── components/ # Auto-registered Vue components (e.g., QuickSearch, signup)
29+
│ ├── composables/ # Core/Firebase composables (e.g., state, auth, storage)
30+
│ ├── layouts/ # Layouts (Default, Public, Signup)
31+
│ ├── middleware/ # Route guards (authPublic, authUserOnly, authSuperAdminOnly)
32+
│ ├── pages/ # Pre-packaged pages (Account, SignIn, SignUp, Admin)
33+
│ ├── public/ # Shared static assets (logos, images)
34+
│ └── utils/ # Shared utility functions (firebase, io)
35+
├── playground/ # Live demo and development environment
36+
└── test/ # Vitest-based integration and unit tests
37+
```
38+
39+
### 1. SPA/Client-Only Design
40+
- **SSR Compatibility:** This module is explicitly designed for Client-Only SPA deployments.
41+
- **Enforcement:** In `src/module.ts`, a check is performed on `nuxt.options.ssr`. If it is `true`, a warning is logged and SSR is programmatically disabled (`nuxt.options.ssr = false`).
42+
43+
### 2. Auto-import Registrations (Module Setup)
44+
- **Components:** Injected using `addComponentsDir` pointing to `src/runtime/components`.
45+
- **Composables & Utils:** Registered via `addImportsDir` from `src/runtime/composables`, `src/runtime/composables/firebase`, and `src/runtime/utils`.
46+
- **Middlewares:**
47+
- `auth-public` (`src/runtime/middleware/authPublic.ts`)
48+
- `auth-user-only` (`src/runtime/middleware/authUserOnly.ts`)
49+
- `auth-super-admin-only` (`src/runtime/middleware/authSuperAdminOnly.ts`)
50+
- **Route Rules:** Applied globally inside the module:
51+
- `/**` uses `auth-user-only`.
52+
- `/signin` & `/signup` use `auth-public`.
53+
- `/admin/**` uses `auth-super-admin-only`.
54+
55+
### 3. Layouts & Pages
56+
- Inject default layouts: `default`, `public`, `signup`.
57+
- Inject standard paths dynamically via `extendPages`:
58+
- `/` -> `IndexPage.vue`
59+
- `/signin` -> `SignIn.vue`
60+
- `/signup` -> `SignUp.vue`
61+
- `/signout` -> `SignOut.vue`
62+
- `/account` -> `AccountPage.vue`
63+
- `/admin` -> `AdminIndex.vue`
64+
- `/admin/users` -> `UsersIndex.vue`
65+
- `/admin/users/:uid` -> `UserIndex.vue`
66+
67+
---
68+
69+
## Development Conventions & Guidelines
70+
71+
### 1. Vue Composition API & SFC Syntax
72+
- Always write Vue SFCs using `<script setup lang="ts">`.
73+
- Lean heavily on modern reactivity features such as `defineModel()` for two-way state binding (e.g., as done in `QuickSearch.vue`).
74+
- Do not add explicit imports for auto-imported Nuxt or Vue composables when writing user-facing code, but **explicitly import from `#imports`** when writing module runtime code (e.g., `import { defineNuxtRouteMiddleware, navigateTo } from '#imports'`).
75+
76+
### 2. Extensibility and Overrides
77+
- Nuxtify is built to be easily customizable. A core concept is **progressive upgrading**.
78+
- If a host application needs to override a component, layout, composable, or utility from Nuxtify, it simply creates a file with the **same name** in its local directory (e.g., local `components/QuickSearch.vue` will override the module's `QuickSearch.vue`). Keep this in mind when making structural changes.
79+
80+
### 3. Code Style and Linters
81+
- Code formatting and style are governed by **ESLint flat config (v9)**.
82+
- Ensure ESLint issues are resolved before opening a PR. Use `npm run lint` and `npm run lint:fix`.
83+
84+
---
85+
86+
## Tooling & Command Reference
87+
88+
| Command | Purpose |
89+
|---------|---------|
90+
| `npm install` | Installs dependencies across the workspace. |
91+
| `npm run dev:prepare` | Builds stubs and prepares the playground types (essential after cloning or making option/interface changes). |
92+
| `npm run dev` | Starts the playground development environment with hot reload. |
93+
| `npm run dev:build` | Compiles the playground Nuxt application. |
94+
| `npm run prepack` | Compiles the Nuxt module into `dist/` ready for publication. |
95+
| `npm run lint` | Runs ESLint validation across the repository. |
96+
| `npm run lint:fix` | Runs ESLint and automatically corrects auto-fixable code style issues. |
97+
| `npm run test` | Executes unit and integration tests via Vitest in one-shot mode. |
98+
| `npm run test:watch` | Runs Vitest in interactive watcher mode. |
99+
| `npm run test:types` | Performs full type checks across the source and the playground with `vue-tsc`. |

0 commit comments

Comments
 (0)