console/AGENTS.md

Appwrite Console - Copilot Instructions

Repository Overview

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.

Critical Build & Test Commands

Setup (REQUIRED before any commands)

1. Install pnpm: npm install -g corepack && corepack enable && corepack prepare pnpm@10.15.1 --activate
2. Create .env: cp .env.example .env (configure PUBLIC_APPWRITE_ENDPOINT and PUBLIC_CONSOLE_MODE)
3. Configure network access (if using GitHub Actions or restricted environments):
   • Ensure firewall/proxy allows access to: pkg.pr.new, pkg.vc, registry.npmjs.org
   • These domains are required for dependencies: @appwrite.io/console, @appwrite.io/pink-icons-svelte, @appwrite.io/pink-svelte
   • In GitHub Actions: Use pnpm/action-setup@v4 which handles registry configuration
   • If network errors persist, check proxy settings: npm config get proxy and npm config get https-proxy
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)

Development Commands

Standard workflow: check → lint → test → build (before committing)

• pnpm run check - TypeScript/Svelte validation (~30-60s)
• pnpm run lint - ESLint check (~10-20s)
• pnpm run format - Auto-fix Prettier formatting
• pnpm run test - Vitest unit tests with TZ=EST (~10-30s)
• pnpm run build - Production build via build.js (~60-120s)
• pnpm dev - Dev server on port 3000
• pnpm run preview - Preview build on port 4173
• pnpm run e2e - Playwright tests (needs pnpm exec playwright install --with-deps chromium first, ~120s+)

CI Pipeline (.github/workflows/tests.yml): audit → install → check → lint → test → build

Project Structure

src/
├── lib/                    # Reusable logic ($lib alias)
│   ├── components/         # Feature components (billing, domains, permissions, etc.)
│   ├── elements/           # Basic UI elements
│   ├── helpers/            # Utility functions (array, date, string, etc.)
│   ├── stores/             # Svelte stores for state
│   ├── sdk/                # Appwrite SDK wrappers
│   └── constants.ts, flags.ts, system.ts
├── routes/
│   ├── (console)/          # Auth-required routes
│   │   ├── organization-[organization]/
│   │   └── project-[region]-[project]/  # databases, functions, messaging, storage
│   └── (public)/           # Public routes (login, register, auth callbacks)
├── themes/                 # Theme definitions ($themes alias)
└── app.html, hooks.{client,server}.ts, service-worker.ts

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].

Key Configuration

svelte.config.js: Adapter = static SPA (fallback: index.html), base path /console, aliases: $lib, $routes, $themes
vite.config.ts: Dev port 3000, Vitest (client=jsdom, server=node), test files: src/**/*.{test,spec}.{js,ts}
tsconfig.json: Extends .svelte-kit/tsconfig.json, NOT strict mode (strict: false)
eslint.config.js: Flat config (ESLint 9+), many rules disabled (see TODOs)
.prettierrc: 4 spaces, single quotes, 100 char width, no trailing commas

Testing

Unit (Vitest): Tests in src/lib/helpers/*.test.ts, run with TZ=EST (timezone matters). Setup mocks SvelteKit ($app/*) in vitest-setup-client.ts.
E2E (Playwright): Tests in e2e/journeys/*.spec.ts, needs build+preview on port 4173, retries 3x, timeout 120s, Chromium only.

Common Pitfalls

1. Blank page in dev: Disable ad blockers if seeing "Failed to fetch dynamically imported module" (known SvelteKit issue)
2. Network errors on install:
   • pkg.pr.new/pkg.vc deps may fail due to firewall/proxy restrictions
   • Check access: curl -I https://pkg.pr.new and curl -I https://pkg.vc
   • Configure proxy if needed: npm config set proxy http://proxy:port and npm config set https-proxy http://proxy:port
   • GitHub Actions: Ensure runner has internet access; use pnpm/action-setup@v4 action
   • Local dev: Often safe to continue with cached versions if network fails
3. OOM on build: Set NODE_OPTIONS=--max_old_space_size=8192 (like Dockerfile does)
4. Test failures: Always use pnpm run test (sets TZ=EST), not vitest directly
5. TS errors not showing: Run pnpm run check explicitly (dev server doesn't always surface them)
6. Format vs lint conflicts: Run pnpm run format before pnpm run lint
7. E2E timeouts: Wait 120s for preview server startup, tests auto-retry 3x
8. Stale build: Clear .svelte-kit if changes not reflected: rm -rf .svelte-kit && pnpm run build

Code Conventions

• Imports: Use $lib, $routes, $themes aliases
• Components: PascalCase, in src/lib/components/[feature]/
• Helpers: Pure functions in src/lib/helpers/
• Types: Inline or .d.ts, not .types.ts files
• Comments: Minimal, use for TODOs or complex logic
• TypeScript: Not strict mode, any tolerated

Workflow

1. Run Appwrite backend locally (see docs)
2. Configure .env with backend endpoint
3. pnpm install --frozen-lockfile
4. pnpm dev (hot reload on port 3000)
5. Before commit: pnpm run check && pnpm run format && pnpm run lint && pnpm run test && pnpm run build
6. Take screenshots: For any UI changes, capture screenshots and include them in the PR description or comments before finalizing

Required Pre-Completion Checklist

CRITICAL: Before finishing any work or marking a task complete, agents MUST run the following commands in order and ensure all pass:

1. pnpm run format - Auto-fix all formatting issues
2. pnpm run check - Verify TypeScript/Svelte types (must show 0 errors, 0 warnings)
3. pnpm run lint - Check code style (ignore pre-existing issues in files you didn't modify)
4. pnpm run test - Run all unit tests (all tests must pass)
5. pnpm run build - Ensure production build succeeds

If any command fails:

• Format/Lint: Run pnpm run format to auto-fix, then re-check
• Type errors: Fix all TypeScript errors in files you modified
• Test failures: Fix failing tests or ensure failures are unrelated to your changes
• Build failures: Debug and resolve build issues before proceeding

Never skip these checks - they are mandatory quality gates before any work is considered complete.

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.