# Onboard to an Unfamiliar Qwik Codebase with Atlas in 2026

> Atlas helps Qwik developers in 2026 build a working mental model of unfamiliar codebases by leveraging semantic search and understanding Qwik's unique `$` boundary and `component$` definitions.

Atlas empowers Qwik developers in 2026 to rapidly build a working mental model of unfamiliar codebases by starting from meaning, not filenames, and integrating directly with the Qwik toolchain, including `vitest`, `pnpm`, and `prettier`. It uses semantic indexing to pinpoint relevant `component$` definitions and `routeLoader$` exports, allowing you to understand core logic and state management with `useSignal` and `useStore` efficiently.

## Key takeaways

- Atlas uses semantic search to understand Qwik `component$` definitions and `routeLoader$` exports.
- The `glob` tool quickly reveals Qwik project structure, including `src/routes` and `vite.config.ts`.
- Atlas's `lsp` tool allows tracing `useSignal` and `useStore` definitions across Qwik files.
- Read-only `explore` subagents safely search for Qwik `$` boundaries and `routeAction$` patterns.
- Atlas provides unified diffs for all Qwik code edits, like `zod$` validation additions, before writing.
- Atlas integrates with `pnpm`, `vitest`, and `prettier` for a complete Qwik development workflow.

## How Atlas uses semantic search to understand Qwik code

In 2026, Atlas begins your Qwik onboarding journey by querying a semantic index, not just filenames, to understand the codebase's core concepts. This approach allows it to identify relevant `component$` definitions and `routeLoader$` exports across hundreds of files, providing a ranked list of snippets and paths that directly answer your plain-language questions.

Atlas's `codebase_search` tool is foundational for Qwik onboarding. Instead of relying on keyword matching alone, it uses hybrid semantic and keyword retrieval, fused by reciprocal rank fusion, to understand the intent behind your queries. For a Qwik project, this means you can ask 'how requests are authenticated' or 'where `useStore` is used for global state' and Atlas will return snippets from files like `src/routes/auth/login/index.tsx` or `src/components/store/global-state.tsx` that are semantically relevant. This capability is powered by Atlas's AST declaration indexing using tree-sitter, ensuring it understands the structure of your Qwik components and their associated logic, rather than just blind line windows. You can even build this index with local Ollama embeddings, keeping your proprietary Qwik code off third-party servers.

## Exploring Qwik project structure with Atlas glob

Before diving into specific files, Atlas helps you grasp the overall Qwik project structure in 2026 using its `glob` tool. This allows you to quickly map the top-level directories and understand naming conventions, such as how `src/routes` organizes pages and API endpoints, without opening a single file.

Understanding the directory layout is crucial for any Qwik project. Atlas's `glob` tool provides an immediate overview, letting you see how `src/routes` contains your `routeLoader$` and `routeAction$` definitions, or where common `component$` files reside. For instance, running `atlas glob 'src/*'` might reveal `src/components`, `src/routes`, `src/services`, and `src/utils`. This quick scan helps you infer the project's architecture and where to expect specific Qwik idioms, like `index.tsx` files defining route entry points or `layout.tsx` files for shared UI. This initial structural understanding complements the semantic search by providing context for the file paths returned.

## Deep diving into Qwik components and state with Atlas LSP

Once you have a high-level understanding, Atlas allows you to deep dive into critical Qwik files in 2026, focusing on `component$` definitions and state management with `useSignal` or `useStore`. By reading the top two or three files identified by `codebase_search`, you can then use the `lsp` tool's `goToDefinition` operation to follow imports and build a precise mental model.

After identifying key files through `codebase_search`, such as a `routeLoader$` in `src/routes/dashboard/index.tsx` or a `component$` in `src/components/user-profile.tsx`, Atlas's `read` tool lets you inspect their contents. From there, the `lsp` tool becomes invaluable. If a `component$` imports a `useStore` hook from `src/store/user.ts`, you can use `lsp goToDefinition` to jump directly to that definition, understanding how global state is managed. This allows you to trace the flow of data and reactivity across your Qwik application, from `useSignal` declarations to `routeAction$` handlers, without manually navigating the file system. Atlas's ability to connect to Model Context Protocol servers exposes these powerful LSP tools directly to the agent, making navigation direct.

## Delegating wide Qwik codebase exploration to Atlas subagents

For broader exploration of a Qwik codebase in 2026, Atlas delegates wide sweeps to its `explore` subagent, ensuring read-only safety. This subagent, defined with a deny-by-default permission set, can safely `grep` for `$` boundaries or `glob` for all `routeAction$` exports across `src/routes` without risking any unintended modifications.

When you need to understand patterns across a large Qwik codebase, the `explore` subagent is your go-to. You can use the `task` tool to instruct it, for example: `atlas task 'explore all files in src/routes for routeAction$ definitions'`. The `explore` subagent is permissioned read-only, allowing only `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`. This means it can safely search for all instances of `useSignal` or `useStore` across your `src/components` directory, or identify all `vite.config.ts` files that load the `qwikCity` plugin, without ever being able to modify a single line of code. This fan-out capability, running in parallel background sessions, significantly accelerates the discovery phase of onboarding.

## Ensuring safety and review for Qwik code changes with Atlas

Atlas prioritizes safety and review for any proposed Qwik code changes in 2026, ensuring you maintain full control. Every Atlas tool call is permission-gated, and any edits, such as moving eager work behind a `$` boundary or adding a `routeAction$` with `zod$` validation, are presented as a unified diff for your explicit approval.

Atlas's safety mechanisms are robust. Before any tool runs, it checks against allow, ask, and deny rules. When Atlas drafts a plan to, for example, refactor a `component$` to optimize for resumability by moving eager work behind a `$` boundary, it does so in a read-only plan agent. Only after your approval does it switch to a build agent. For every file edit, such as adding a new `routeAction$` to `src/routes/api/submit.ts` complete with `zod$` validation, Atlas computes a unified diff and surfaces it for your approval. This ensures you see exactly what changes are proposed before they are written. Furthermore, Atlas snapshots file changes as git patches, allowing edits to be diffed and rolled back easily, providing an additional layer of security and control over your Qwik codebase.

## Steps

1. Ask Atlas's `codebase_search` a plain-language question about your Qwik project, like 'how are `routeLoader$` functions defined in `src/routes`?' to get ranked snippets and file paths.
2. Run `atlas glob 'src/*'` on the top-level directories to quickly see the Qwik package layout and naming conventions, such as the structure of `src/routes` and `src/components`.
3. Use `atlas read` on the two or three Qwik files `codebase_search` ranked highest, then follow `component$` imports or `useStore` definitions with `atlas lsp goToDefinition`.
4. Delegate wide sweeps to the `explore` subagent via `atlas task 'grep for all `$` boundaries in `src/components`'` to understand resumability patterns, knowing it's read-only.
5. Record what you learned about Qwik's `useSignal` or `routeAction$` implementations as a `todowrite` list so open questions persist into the next turn.
6. If Atlas proposes changes, like adding a `routeAction$` with `zod$` validation, review the unified diff and approve before it runs `prettier` over the touched Qwik components.
7. Verify any generated Qwik code by running `pnpm run vitest` to ensure all tests pass after Atlas's modifications.

## FAQ

### How does Atlas understand Qwik's resumability and `$` boundary?

Atlas indexes Qwik code by AST declarations using tree-sitter, allowing it to recognize `component$` definitions, `useSignal` and `useStore` state, and crucially, the `$` boundary. This enables it to suggest moving eager work behind a `$` boundary for optimal lazy chunking, directly addressing Qwik's core resumability model.

### Can Atlas help me find all `routeLoader$` and `routeAction$` functions?

Yes, Atlas can efficiently locate all `routeLoader$` and `routeAction$` exports within your `src/routes` directory. You can use `codebase_search` for semantic queries or delegate a `task` to the `explore` subagent to `grep` for these specific Qwik idioms across your codebase.

### How does Atlas ensure code quality for Qwik projects?

Atlas integrates with standard Qwik tooling. After making any changes, such as adding a `routeAction$` with `zod$` validation, Atlas can run `prettier` over the touched components to maintain formatting consistency. It also encourages running `pnpm run vitest` to verify functionality.

### Is my Qwik code safe when using Atlas's AI features?

Absolutely. Atlas prioritizes safety. It builds its code index with local Ollama embeddings, keeping your Qwik code off third-party servers. Every tool call is permission-gated, and all proposed changes are presented as a unified diff for your explicit approval before being written to disk. Atlas also snapshots changes as git patches for easy rollback.

### Can Atlas help me refactor Qwik state management from `useSignal` to `useStore`?

While Atlas excels at understanding and navigating `useSignal` and `useStore` patterns, direct refactoring from one to the other would involve a complex series of edits. Atlas can assist by identifying all instances of `useSignal` and `useStore`, helping you plan the refactor, and then applying changes with diff approval, but it would require careful guidance.

### How does Atlas handle Qwik's `vite.config.ts` and `qwikCity` plugin?

Atlas is designed to operate within projects that have a `vite.config.ts` loading the `qwikCity` plugin. It understands the context provided by this configuration, allowing it to correctly interpret `src/routes` for `routeLoader$` and `routeAction$` definitions, and other Qwik-specific project structures.

---

Canonical HTML: https://runatlas.sh/resources/stacks/onboard-to-an-unfamiliar-codebase-in-qwik
Source of truth: aeo_pages row `/resources/stacks/onboard-to-an-unfamiliar-codebase-in-qwik` (segment: Stacks) (this file is generated from it, never hand-edited).
Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.