Goal: Replace client-side fetch calls to internal API routes with SolidStart query()/createAsync() for reads and action() for writes. This keeps data loading SSR-friendly and avoids ad-hoc fetch in UI components.
- UI code calls fetch()/apiFetch() for app data.
- A route under app/src/routes/api is only used by the app itself.
- The endpoint is a read (query) or write (action) and does not need to be exposed as a public HTTP API.
- Identify the API route and the client caller(s).
- Move the server logic into a shared module (not under routes/).
- Expose:
- query() for reads
- action() for writes
- Update UI code to call the query/action (no fetch in the component).
- Remove the now-unused API route (if nothing else depends on it).
- Verify behavior (type-check/build; manual click-through if needed).
None. All app callers now use query()/action().
Notes
- HTTP route still kept for signed-in clients (e2e fixtures): POST /api/docs. Bulk ingest and /api/docs/inventory were removed.
Queries (GET)
- /api/magic-session
- /api/embeddings/runs
- /api/embeddings/runs/[id]
- /api/embeddings/runs/docs/[docId]/sections
- /api/umap/runs
- /api/umap/points
- /api/umap/runs/[id]
- /api/docs
- /api/docs/[id]
- /api/docs/search
- /api/docs/sources
- /api/docs/paths
- /api/docs/meta/keys
- /api/docs/meta/values
- /api/ai/runs
- /api/ai/runs/[id]
- /api/ai/models
- /api/ai/chat/threads
- /api/ai/chat/threads/[id]
- /api/prompts
- /api/prompts/[id]
Actions (POST/PUT/PATCH/DELETE)
- /api/magic-login
- /api/logout
- /api/embeddings/runs (POST)
- /api/embeddings/runs/[id] (POST/PATCH/DELETE)
- /api/umap/runs (POST)
- /api/umap/runs/[id] (PATCH/DELETE)
- /api/docs (POST/DELETE)
- /api/docs/[id] (PUT/DELETE)
- /api/docs/source (POST/DELETE)
- /api/docs/path-round (POST)
- /api/docs/bulk-delete (POST)
- /api/docs/bulk-meta (POST)
- /api/docs/scan-relative-images (POST)
- /api/ai/runPrompt (POST)
- /api/ai/promptDesigner (POST)
- /api/ai/chat/threads (POST)
- /api/ai/chat/threads/[id] (PATCH)
- /api/ai/chat/threads/[id]/messages (POST)
- /api/ai/chat/messages/[id] (PATCH/DELETE)
- /api/prompts (POST)
- /api/prompts/[id] (PUT/DELETE)
- /api/prompts/[id]/activate (POST)
- /api/prompts/[id]/versions (POST)
- /api/prompts/[id]/revise (POST)
- /api/docs/cleanup-titles (POST) -- route removed; now query/action only
Notes
- Some HTTP routes remain to support external clients (e.g. CLI ingest/inventory).
- Server module
- Create a file near the feature, e.g. app/src/features//data/*.ts
- Import prisma (or other server deps) directly in the module.
- Export named functions using query() and action().
- In action() bodies, include "use server" as the first statement.
- Keep types in the same file.
- UI module
- Read:
- Use createAsync(() => myQuery(args)) when data is shown in the UI.
- For on-demand reads, it is OK to call the query directly and await it.
- Write:
- Use useAction(myAction) and call the returned function.
- Remove any fetch()/apiFetch() usage tied to internal routes.
- Read:
- Route cleanup
- Delete the old app/src/routes/api/... file once no callers remain.
- If an external client still depends on the HTTP route, keep the route and consider calling the shared query/action from it.
- Read
- server module: export const getThing = query(async (id: string) => { ... }, "thing");
- UI module: const thing = createAsync(() => getThing(id()));
- Write
- server module: export const saveThing = action(async (payload) => { "use server"; ... }, "save-thing");
- UI module: const runSave = useAction(saveThing); await runSave(payload);
- Query functions (from
query()) work best withcreateAsync()in UI, notcreateResource(). - When using
createAsync()for list data, re-fetch withrevalidate(query.keyFor(args))instead ofrefetch. - Remove AbortSignal plumbing tied to
fetch(e.g.,useAbortableFetch) when calls move toquery()since queries manage their own caching. - Prefer small, scoped data modules (types, queries, actions) to keep files <200 LOC and make conversions easier.
- Keep server-side types local to the module and export only the client-facing types.
- Using fetch() in UI for app data (prefer query/action).
- Putting shared logic under app/src/routes/ (keep routes for routing only).
- Forgetting to remove stale API routes after migration.
- Using props destructuring in Solid components (breaks reactivity).
- For reads that are part of the page UI, prefer createAsync() so SSR can preload data and keep the loading state consistent.
- For mutations, action() provides the correct client-server wiring without manual fetch.