116 lines
5.9 KiB
Markdown
116 lines
5.9 KiB
Markdown
# Chitai frontend
|
|
|
|
SvelteKit web app for the eBook library. See the repo-root `AGENTS.md` for the overall picture and
|
|
dev-environment setup.
|
|
|
|
**Stack:** SvelteKit 2 with `adapter-node` · Svelte 5 (runes) · Tailwind v4 · Zod v4 ·
|
|
`epubjs` · `mode-watcher` (dark mode) · `svelte-sonner` (toasts) · pnpm.
|
|
|
|
Two experimental flags are on in `svelte.config.js` and the codebase depends on both:
|
|
`kit.experimental.remoteFunctions` and `compilerOptions.experimental.async` (`await` in components).
|
|
|
|
Tailwind v4 has **no config file** — the theme, oklch colour tokens and `@custom-variant dark` all
|
|
live in `src/app.css`.
|
|
|
|
## Talking to the backend
|
|
|
|
There are two mechanisms; pick deliberately.
|
|
|
|
**1. Remote functions — the default.** `src/lib/api/*.remote.ts` export `query` / `command` / `form`
|
|
functions from `$app/server`. Each takes a Zod schema from `$lib/schema` as its validator and runs
|
|
on the server, reaching the API through `locals.api` (the `ApiClient` in `src/lib/server/api.ts`):
|
|
|
|
```ts
|
|
export const getBook = query(stringCoerce, async (id): Promise<Book> => {
|
|
const { locals } = getRequestEvent();
|
|
const response = await locals.api.get(`/books/${id}`);
|
|
if (!response.ok) error(response.status === 404 ? 404 : 500, '…');
|
|
return await response.json();
|
|
});
|
|
```
|
|
|
|
Conventions: build query strings with `createQueryParams` from `$lib/utils`; on a failed response
|
|
throw SvelteKit's `error(status, message)`; multipart uploads go through `postMultipart` /
|
|
`putMultipart`. Re-export new modules from `src/lib/api/index.ts`.
|
|
|
|
**2. The catch-all proxy** at `src/routes/api/[...path]/+server.ts` forwards GET/POST/PATCH/DELETE
|
|
to the backend with the auth header attached. Use it only where the **browser itself** must fetch
|
|
the backend — e.g. streaming a book file into the EPUB/PDF reader. It is not the general-purpose
|
|
path.
|
|
|
|
## Auth
|
|
|
|
`src/hooks.server.ts` is a `sequence` of two handles: the first reads the `authToken` cookie,
|
|
constructs an `ApiClient`, validates it with `GET /access/me` and fills `locals.user` /
|
|
`locals.authToken` / `locals.api` (clearing the cookie if invalid); the second redirects any route
|
|
outside `/login` to the login page when there is no user.
|
|
|
|
The cookie is set in `src/lib/api/auth.remote.ts` (`login`) — httpOnly, secure, sameSite strict, one
|
|
week — and deleted by `logout`. The backend JWT never reaches client-side JS.
|
|
|
|
## Schemas
|
|
|
|
- `src/lib/schema/*.ts` — hand-written Zod schemas, used as remote-function input validators and as
|
|
the source of the exported TS types. Mirror `backend/src/chitai/schemas/` when the API changes.
|
|
- `src/lib/schema/common.ts` — shared building blocks: `stringCoerce` / `arrayCoerce` coercion
|
|
helpers, `PaginatedResponse<T>`, and the pagination / search / order query schemas that most list
|
|
endpoints compose from.
|
|
- `src/lib/schema/openapi/schema.d.ts` — **generated** from the backend's OpenAPI document with
|
|
`openapi-typescript`. Never hand-edit; regenerate after backend API changes.
|
|
|
|
## State
|
|
|
|
Client state lives in classes in `src/lib/state/*.svelte.ts` using `$state` / `$derived`, shared via
|
|
Svelte context with a module-level `Symbol` key and a `setXState` / `getXState` pair:
|
|
|
|
```ts
|
|
const LIBRARY_KEY = Symbol('LIBRARY');
|
|
export function setLibraryState(libraries: Library[]) { return setContext(LIBRARY_KEY, new LibraryState(libraries)); }
|
|
export function getLibraryState() { return getContext<ReturnType<typeof setLibraryState>>(LIBRARY_KEY); }
|
|
```
|
|
|
|
Follow that pattern rather than introducing stores. `library.svelte.ts` is the reference — including
|
|
its optimistic-delete-with-rollback and toast handling. `bookCollection` / `bookSelection` /
|
|
`bookOperations` split list data, selection and mutations across three cooperating classes.
|
|
|
|
## Components
|
|
|
|
- `src/lib/components/ui/` — vendored shadcn-svelte (`components.json`) plus jsrepo blocks from
|
|
`@ieedan/shadcn-svelte-extras` (`jsrepo.json`). Treat as generated: add components with the CLIs
|
|
rather than hand-writing them, and prefer wrapping over editing.
|
|
- App components live in `forms/`, `layout/`, `view/` (browser, grid/list/table, filters, sort) and
|
|
`reader/` (epub reader + chapter sidebar).
|
|
- `cn()` from `$lib/utils` merges Tailwind classes; the `WithElementRef` / `WithoutChild` helpers
|
|
there are the shadcn prop-typing conventions.
|
|
|
|
## Routing
|
|
|
|
Route groups carry the layout structure:
|
|
|
|
- `(root)` — the authenticated shell (sidebar, header); `+layout.server.ts` loads the libraries.
|
|
- `(root)/(library)` — library-scoped pages: `library/[libraryId]/view`, `book/[bookId]`, edit, and
|
|
the readers at `book/[bookId]/read/{epub,pdf}/[fileId]`.
|
|
- `+layout@.svelte` breakouts reset to the root layout for the login page and the full-screen reader.
|
|
|
|
## Conventions
|
|
|
|
Prettier (`.prettierrc`): tabs, single quotes, no trailing commas, 100 columns, with the Svelte and
|
|
Tailwind plugins. Run `pnpm check` (svelte-check) and `pnpm lint` before considering work done.
|
|
|
|
## Known rough edges
|
|
|
|
Observed in the current tree — don't mistake these for intentional patterns to copy:
|
|
|
|
- `src/lib/schema/openapi/schema.d.ts` is **stale** — it predates the `BookProgress` rework and has
|
|
no `BookProgressRead`, so `book.progress` types as `{}`. This is the source of most of the ~104
|
|
errors `pnpm check` reports on a clean tree; regenerating it should clear them. Get a baseline
|
|
before assuming an error is yours.
|
|
- `src/routes/api/[...path]/+server.ts` — all four handlers are annotated `RequestHandler` while the
|
|
import of that type is commented out at line 4.
|
|
- `src/app.d.ts` — `App.Locals["user"]` is typed from `lucide-svelte`'s `User` *icon* component
|
|
rather than the `User` interface in `$lib/server/auth`.
|
|
- Uncommitted work in progress (as of 2026-08-10): library icons, spanning
|
|
`components/ui/icon-picker/`, the newly vendored `components/ui/popover/`,
|
|
`forms/library-create-form.svelte`, `layout/library-switcher.svelte` and `schema/library.ts`.
|
|
Prefer not to refactor those files mid-flight.
|