|
| 1 | +# Appwrite Console - Copilot Instructions |
| 2 | + |
| 3 | +## Repository Overview |
| 4 | + |
| 5 | +Appwrite Console is the web-based GUI for the Appwrite backend-as-a-service platform. Single-page application built with **Svelte 5 + SvelteKit 2**, **TypeScript** (not strict mode), **Vite 7**, tested with **Vitest + Playwright**. Package manager: **pnpm 10.15.1**, Node 20+. ~1500 files with extensive component-based architecture. |
| 6 | + |
| 7 | +## Critical Build & Test Commands |
| 8 | + |
| 9 | +### Setup (REQUIRED before any commands) |
| 10 | + |
| 11 | +1. **Install pnpm**: `npm install -g corepack && corepack enable && corepack prepare pnpm@10.15.1 --activate` |
| 12 | +2. **Create .env**: `cp .env.example .env` (configure `PUBLIC_APPWRITE_ENDPOINT` and `PUBLIC_CONSOLE_MODE`) |
| 13 | +3. **Configure network access** (if using GitHub Actions or restricted environments): |
| 14 | + - Ensure firewall/proxy allows access to: `pkg.pr.new`, `pkg.vc`, `registry.npmjs.org` |
| 15 | + - These domains are required for dependencies: `@appwrite.io/console`, `@appwrite.io/pink-icons-svelte`, `@appwrite.io/pink-svelte` |
| 16 | + - In GitHub Actions: Use `pnpm/action-setup@v4` which handles registry configuration |
| 17 | + - If network errors persist, check proxy settings: `npm config get proxy` and `npm config get https-proxy` |
| 18 | +4. **Install dependencies**: `pnpm install --frozen-lockfile` (if pkg.pr.new/pkg.vc fail due to network restrictions, installation may still succeed with cached versions) |
| 19 | + |
| 20 | +### Development Commands |
| 21 | + |
| 22 | +**Standard workflow**: `check` → `lint` → `test` → `build` (before committing) |
| 23 | + |
| 24 | +- `pnpm run check` - TypeScript/Svelte validation (~30-60s) |
| 25 | +- `pnpm run lint` - ESLint check (~10-20s) |
| 26 | +- `pnpm run format` - Auto-fix Prettier formatting |
| 27 | +- `pnpm run test` - Vitest unit tests with TZ=EST (~10-30s) |
| 28 | +- `pnpm run build` - Production build via build.js (~60-120s) |
| 29 | +- `pnpm dev` - Dev server on port 3000 |
| 30 | +- `pnpm run preview` - Preview build on port 4173 |
| 31 | +- `pnpm run e2e` - Playwright tests (needs `pnpm exec playwright install --with-deps chromium` first, ~120s+) |
| 32 | + |
| 33 | +**CI Pipeline** (`.github/workflows/tests.yml`): audit → install → check → lint → test → build |
| 34 | + |
| 35 | +## Project Structure |
| 36 | + |
| 37 | +``` |
| 38 | +src/ |
| 39 | +├── lib/ # Reusable logic ($lib alias) |
| 40 | +│ ├── components/ # Feature components (billing, domains, permissions, etc.) |
| 41 | +│ ├── elements/ # Basic UI elements |
| 42 | +│ ├── helpers/ # Utility functions (array, date, string, etc.) |
| 43 | +│ ├── stores/ # Svelte stores for state |
| 44 | +│ ├── sdk/ # Appwrite SDK wrappers |
| 45 | +│ └── constants.ts, flags.ts, system.ts |
| 46 | +├── routes/ |
| 47 | +│ ├── (console)/ # Auth-required routes |
| 48 | +│ │ ├── organization-[organization]/ |
| 49 | +│ │ └── project-[region]-[project]/ # databases, functions, messaging, storage |
| 50 | +│ └── (public)/ # Public routes (login, register, auth callbacks) |
| 51 | +├── themes/ # Theme definitions ($themes alias) |
| 52 | +└── app.html, hooks.{client,server}.ts, service-worker.ts |
| 53 | +``` |
| 54 | + |
| 55 | +**SvelteKit conventions**: `+page.svelte` (component), `+page.ts` (data loader), `+layout.svelte` (wrapper), `+error.svelte` (errors). Groups like `(console)` organize routes without affecting URLs. Dynamic params: `[param]`. |
| 56 | + |
| 57 | +## Key Configuration |
| 58 | + |
| 59 | +**svelte.config.js**: Adapter = static SPA (fallback: index.html), base path `/console`, aliases: `$lib`, `$routes`, `$themes` |
| 60 | +**vite.config.ts**: Dev port 3000, Vitest (client=jsdom, server=node), test files: `src/**/*.{test,spec}.{js,ts}` |
| 61 | +**tsconfig.json**: Extends `.svelte-kit/tsconfig.json`, **NOT strict mode** (`strict: false`) |
| 62 | +**eslint.config.js**: Flat config (ESLint 9+), many rules disabled (see TODOs) |
| 63 | +**.prettierrc**: 4 spaces, single quotes, 100 char width, no trailing commas |
| 64 | + |
| 65 | +## Testing |
| 66 | + |
| 67 | +**Unit (Vitest)**: Tests in `src/lib/helpers/*.test.ts`, run with `TZ=EST` (timezone matters). Setup mocks SvelteKit (`$app/*`) in `vitest-setup-client.ts`. |
| 68 | +**E2E (Playwright)**: Tests in `e2e/journeys/*.spec.ts`, needs build+preview on port 4173, retries 3x, timeout 120s, Chromium only. |
| 69 | + |
| 70 | +## Common Pitfalls |
| 71 | + |
| 72 | +1. **Blank page in dev**: Disable ad blockers if seeing "Failed to fetch dynamically imported module" (known SvelteKit issue) |
| 73 | +2. **Network errors on install**: |
| 74 | + - pkg.pr.new/pkg.vc deps may fail due to firewall/proxy restrictions |
| 75 | + - Check access: `curl -I https://pkg.pr.new` and `curl -I https://pkg.vc` |
| 76 | + - Configure proxy if needed: `npm config set proxy http://proxy:port` and `npm config set https-proxy http://proxy:port` |
| 77 | + - GitHub Actions: Ensure runner has internet access; use `pnpm/action-setup@v4` action |
| 78 | + - Local dev: Often safe to continue with cached versions if network fails |
| 79 | +3. **OOM on build**: Set `NODE_OPTIONS=--max_old_space_size=8192` (like Dockerfile does) |
| 80 | +4. **Test failures**: Always use `pnpm run test` (sets TZ=EST), not `vitest` directly |
| 81 | +5. **TS errors not showing**: Run `pnpm run check` explicitly (dev server doesn't always surface them) |
| 82 | +6. **Format vs lint conflicts**: Run `pnpm run format` before `pnpm run lint` |
| 83 | +7. **E2E timeouts**: Wait 120s for preview server startup, tests auto-retry 3x |
| 84 | +8. **Stale build**: Clear `.svelte-kit` if changes not reflected: `rm -rf .svelte-kit && pnpm run build` |
| 85 | + |
| 86 | +## Code Conventions |
| 87 | + |
| 88 | +- Imports: Use `$lib`, `$routes`, `$themes` aliases |
| 89 | +- Components: PascalCase, in `src/lib/components/[feature]/` |
| 90 | +- Helpers: Pure functions in `src/lib/helpers/` |
| 91 | +- Types: Inline or `.d.ts`, not `.types.ts` files |
| 92 | +- Comments: Minimal, use for TODOs or complex logic |
| 93 | +- TypeScript: Not strict mode, `any` tolerated |
| 94 | + |
| 95 | +## Workflow |
| 96 | + |
| 97 | +1. Run Appwrite backend locally (see [docs](https://appwrite.io/docs/advanced/self-hosting)) |
| 98 | +2. Configure `.env` with backend endpoint |
| 99 | +3. `pnpm install --frozen-lockfile` |
| 100 | +4. `pnpm dev` (hot reload on port 3000) |
| 101 | +5. Before commit: `pnpm run check && pnpm run format && pnpm run lint && pnpm run test && pnpm run build` |
| 102 | +6. **Take screenshots**: For any UI changes, capture screenshots and include them in the PR description or comments before finalizing |
| 103 | + |
| 104 | +**Trust these instructions** - only search if incomplete/incorrect. See CONTRIBUTING.md for PR conventions. Use `--frozen-lockfile` always. Docker builds: multi-stage, final image is nginx serving static files from `/console` path. |
0 commit comments