zaid.marzguioui/myeasycms-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: consolidate AGENTS.md and CLAUDE.md files, update tech stac… (#444)

Browse Source 
* refactor: consolidate AGENTS.md and CLAUDE.md files, update tech stack and architecture details

- Merged content from CLAUDE.md into AGENTS.md for better organization.
- Updated tech stack section to reflect the current technologies used, including Next.js, Supabase, and Tailwind CSS.
- Enhanced monorepo structure documentation with detailed directory purposes.
- Streamlined multi-tenant architecture explanation and essential commands.
- Added key patterns for naming conventions and server actions.
- Removed outdated agent files related to Playwright and PostgreSQL, ensuring a cleaner codebase.
- Bumped version to 2.23.7 to reflect changes.
This commit is contained in:
Giancarlo Buomprisco
2026-01-18 10:44:40 +01:00
committed by GitHub
parent bebd56238b
commit cfa137795b
61 changed files with 3636 additions and 9522 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
AGENTS.md
View File

@@ -1,207 +1,61 @@
This file provides guidance to Claude Code when working with code in this repository.
# Makerkit SaaS Starter
## Core Technologies
## Tech Stack
- **Next.js 16** with App Router
- **Supabase** for database, auth, and storage
- **React 19**
- **TypeScript**
- **Tailwind CSS 4**, Shadcn UI, Lucide React
- **Turborepo**
- **Next.js 16** (App Router) + **React 19** + **TypeScript**
- **Supabase** (Postgres, Auth, Storage)
- **Tailwind CSS 4** + Shadcn UI
- **Turborepo** monorepo
## Monorepo Structure
- `apps/web` - Main Next.js SaaS application
- `apps/web/supabase` - Supabase folder (migrations, schemas, tests)
- `apps/e2e` - Playwright end-to-end tests
- `packages/features/*` - Feature packages
- `packages/` - Shared packages and utilities
| Directory | Purpose | Details |
|-----------|---------|---------|
| `apps/web` | Main Next.js app | See `apps/web/AGENTS.md` |
| `apps/web/supabase` | Database schemas & migrations | See `apps/web/supabase/AGENTS.md` |
| `apps/e2e` | Playwright E2E tests | See `apps/e2e/AGENTS.md` |
| `packages/ui` | UI components (@kit/ui) | See `packages/ui/AGENTS.md` |
| `packages/supabase` | Supabase clients | See `packages/supabase/AGENTS.md` |
| `packages/next` | Next.js utilities | See `packages/next/AGENTS.md` |
| `packages/features` | Feature packages | See `packages/features/AGENTS.md` |
## Multi-Tenant Architecture
**Personal Accounts**: Individual user accounts (auth.users.id = accounts.id)
**Team Accounts**: Shared workspaces with members, roles, and permissions
Data associates with accounts via foreign keys for proper access control.
- **Personal Accounts**: `auth.users.id = accounts.id`
- **Team Accounts**: Shared workspaces with members, roles, permissions
- Data links to accounts via `account_id` foreign key
## Essential Commands
### Development Workflow
```bash
pnpm dev # Start all apps
pnpm dev # Start development
pnpm supabase:web:start # Start local Supabase
pnpm supabase:web:reset # Reset database
pnpm supabase:web:typegen # Generate TypeScript types
pnpm typecheck # Type check
pnpm lint:fix # Fix linting
pnpm format:fix # Format code
```
### Database Operations
## Key Patterns (Quick Reference)
```bash
pnpm supabase:web:start # Start Supabase locally
pnpm --filter web supabase migrations up # Apply new migrations
pnpm supabase:web:reset # Reset with latest schema (clean rebuild)
pnpm supabase:web:typegen # Generate TypeScript types
pnpm --filter web supabase:db:diff # Create migration
```
| Pattern | Import | Details |
|---------|--------|---------|
| Server Actions | `enhanceAction` from `@kit/next/actions` | `packages/next/AGENTS.md` |
| Route Handlers | `enhanceRouteHandler` from `@kit/next/routes` | `packages/next/AGENTS.md` |
| Server Client | `getSupabaseServerClient` from `@kit/supabase/server-client` | `packages/supabase/AGENTS.md` |
| UI Components | `@kit/ui/{component}` | `packages/ui/AGENTS.md` |
| Translations | `Trans` from `@kit/ui/trans` | `packages/ui/AGENTS.md` |
The typegen command must be run after applying migrations or resetting the database.
## Authorization
## Typescript
- **RLS enforces access control** - no manual auth checks needed with standard client
- **Admin client** (`getSupabaseServerAdminClient`) bypasses RLS - use sparingly with manual validation
- Write clean, clear, well-designed, explicit TypeScript
- Avoid obvious comments
- Avoid unnecessary complexity or overly abstract code
- Always use implicit type inference, unless impossible
- You must avoid using `any`
- Handle errors gracefully using try/catch and appropriate error types
- Use service pattern for server-side APIs
- Add `import 'server-only';` to code that is exclusively server-side
- Never mix client and server imports from a file or a package
- Extract self-contained classes/utilities (ex. algortihmic code) from classes that cross the network boundary
## Verification
## React
- Encapsulate repeated blocks of code into reusable local components
- Write small, composable, explicit, well-named components
- Always use `react-hook-form` and `@kit/ui/form` for writing forms
- Always use 'use client' directive for client components
- Add `data-test` for E2E tests where appropriate
- `useEffect` is a code smell and must be justified - avoid if possible
- Do not write many (such as 4-5) separate `useState`, prefer single state object (unless required)
- Prefer server-side data fetching using RSC
- Display loading indicators (ex. with LoadingSpinner) component where appropriate
## Next.js
- Use `enhanceAction` for Server Actions
- Use `use server` in server actions files
- Use `enhanceRouteHandler` for API Routes
- Export page components using the `withI18n` utility
- Add well-written page metadata to pages
- Redirect using `redirect` following a server action instead of using client-side router
- Since `redirect` throws an error, handle `catch` block using `isRedirectError` from `next/dist/client/components/redirect-error` in client-side forms when calling the server action
## Data Fetching Architecture
Makerkit uses a clear separation between data fetching and mutations:
### Server Components with Loaders (Reading Data)
**Pattern**: Use async server components that call loader functions for initial data fetching.
```typescript
// Page component (apps/web/app/home/[account]/page.tsx)
async function TeamAccountPage({ params }: Props) {
const client = getSupabaseServerClient();
const slug = (await params).account;
const [projects, workspace] = await loadProjectsPageData(client, slug);
return <ProjectsList projects={projects} />;
}
// Loader function (_lib/server/projects-page.loader.ts)
import 'server-only';
export async function loadProjectsPageData(
client: SupabaseClient<Database>,
slug: string,
) {
return Promise.all([
loadProjects(client, slug),
loadTeamWorkspace(slug),
]);
}
async function loadProjects(client: SupabaseClient<Database>, slug: string) {
const { data, error } = await client.rpc('get_team_projects', {
account_slug: slug,
});
if (error) throw error;
return data ?? [];
}
```
### Server Actions (Mutations Only)
**Pattern**: Use `enhanceAction` for create/update/delete operations with schema validation.
```typescript
// server-actions.ts
'use server';
import { enhanceAction } from '@kit/next/actions';
export const createProject = enhanceAction(
async (data) => {
const client = getSupabaseServerClient();
const service = createProjectsService();
const response = await service.createProject(data);
if (response.error) {
throw response.error;
}
return {
success: true,
data: response.data,
};
},
{
schema: CreateProjectSchema,
},
);
```
### Authorization & RLS
- **Server Components**: RLS automatically enforces access control
- **Server Actions**: RLS validates permissions on mutations
- **No manual auth checks needed** when using standard Supabase client
- **Admin client**: Only for bypassing RLS (rare cases, requires careful manual validation)
## File Organization Patterns
### Route Structure
```
apps/web/app/home/[account]/
├── page.tsx # Team dashboard
├── members/
│ ├── page.tsx # Members listing
│ └── _lib/server/ # Server-side utilities
│ └── members-page.loader.ts
├── projects/ # New feature example
│ ├── page.tsx # Projects listing
│ ├── [id]/ # Individual project
│ │ └── page.tsx # Project detail page
│ ├── _components/ # Feature-specific components
│ │ ├── project-list.tsx
│ │ └── create-project-form.tsx
│ └── _lib/
│ ├── server/ # Server-side logic
│ │ ├── projects-page.loader.ts
│ │ └── projects-server-actions.ts
│ └── schemas/ # Zod validation schemas
│ └── project.schema.ts
└── _components/ # Shared team account components
└── team-account-layout-page-header.tsx
```
### Naming Conventions
- **Pages**: `page.tsx` (Next.js convention)
- **Loaders**: `{feature}-page.loader.ts`
- **Actions**: `{feature}-server-actions.ts`
- **Schemas**: `{feature}.schema.ts`
- **Components**: `kebab-case.tsx`
## UI Components
UI Components are placed at `packages/ui`. Call MCP tool to list components to verify they exist.
## Verification Steps
After implementation:
1. **Run `pnpm typecheck`** - Must pass without errors
2. **Run `pnpm lint:fix`** - Auto-fix issues
3. **Run `pnpm format:fix`** - Format code
After implementation, always run:
1. `pnpm typecheck`
2. `pnpm lint:fix`
3. `pnpm format:fix`
4. Run code quality reviewer agent