# Supported projects and limitations

Critter supports plain HTML prototypes, Vite apps, and Next.js apps that can be statically exported. It keeps your current interface live and makes previous Git commits available as interactive previews.

## Compatibility

| Project or requirement | What to expect |
| --- | --- |
| HTML, CSS, and JavaScript | Supported directly in a Git repository. No `package.json`, dependency installation, or build command is required. |
| Vite | Supported when the project has the development and build scripts needed to run and build its UI. |
| Next.js | Supported when the relevant pages work as a static export. Runtime server features are not part of a historical snapshot. |
| Package managers | npm, Yarn, pnpm, and Bun are supported for framework apps. The project's matching package manager must be available. |
| Repositories with multiple apps | Select a framework app with `critter view --app apps/admin`, using its actual path. |
| Several projects at once | Each viewer chooses its own local ports. The same app reuses its existing viewer unless you pass `--new-instance`. |
| Existing Git history | Ordinary commits appear in the viewer. A historical HTML page must exist in the selected commit; a framework version must still build. |

The CLI requires **Node.js 18 or newer and Git**. Your framework app or package manager may require a newer Node.js version. Start with [the installation guide](/docs/getting-started/).

## HTML files and website roots

An explicit file command, such as `critter view prototypes/checkout.html`, uses the Git repository as the website root. This keeps shared assets and sibling pages available. The page is pinned across versions and comparisons.

A directory command, such as `critter view prototypes/`, uses that directory as the website root. Critter opens `index.html` or shows a chooser when the directory contains other HTML pages. Selecting a page pins it across versions too. The history only lists commits that changed that directory, so work in sibling folders stays out of the way.

Root-relative URLs such as `/assets/style.css` start at the selected website root. Pass another HTML file to `critter view` to change the selection in an existing viewer. Directory detection prefers Vite or Next.js when those dependencies are present; an explicit HTML file selects raw HTML mode.

`critter doctor` accepts the same file or directory, such as `critter doctor prototypes/`, and checks an HTML setup without looking for a `package.json` or build scripts.

HTML mode expects files a browser can run directly. It does not compile TypeScript or JSX, resolve npm imports, inject environment variables, or provide a backend. Use the framework workflow if your app needs those build steps.

## What historical versions preserve

Versions are prepared on demand and stored in Critter's per-user cache outside the repository. HTML snapshots use committed files without running install or build scripts. Framework snapshots install dependencies and build the selected commit.

The live interface can include your current edits. Historical versions contain the code and local assets saved in that commit. Missing historical HTML pages show an explanation instead of silently opening a different page.

Static HTML previews exclude hidden files, including `.git` and `.env`, as well as symlinks, `node_modules`, and private-key files. Keep the source and supporting assets you want to revisit committed in Git.

These are interactive pages, not a recording of the whole application environment. Git history does not restore database contents, user accounts, browser storage, or remote services. External images, fonts, APIs, and other resources are fetched from their current hosts.

## Next.js and backend-dependent screens

A historical Next.js snapshot must work without a running Next.js server. API routes, request-time server rendering, and other runtime server features are not provided by that static snapshot. `critter doctor` identifies common framework setup problems, including Next.js API-route directories; it is not proof that every route will export successfully.

For UI review, local fixtures or a suitable demo data environment make comparisons more consistent. Keep any required external backend available separately, and verify that the route works in a static build.

## Environment and external data

For framework snapshots, Critter omits values from your current `.env.local`, including variables with public-looking names. To deliberately provide a build value, export it in the shell and name it when starting the viewer:

```bash
export VITE_API_URL=http://localhost:3000
critter view --build-env VITE_API_URL
```

Use the variable name and value appropriate for your app. Repeat `--build-env` for additional variables. If a viewer is already running for that app, stop it before relaunching with new build configuration.

This option affects historical framework builds; the live app runs in your normal development environment. HTML mode does not use `--build-env` or inject environment variables.

Build scripts still execute with your user's permissions. They are not a filesystem sandbox, and committed configuration or code can access external services. Use trusted repositories and appropriate non-production configuration when reviewing historical code.

## What comparison highlights mean

Critter highlights changes in rendered content, appearance, layout, and state. Hovering a change shows the old and new values of each changed property. These highlights help you inspect an interface; they are not pixel-perfect image diffs, automated design judgments, or a substitute for testing the application. They appear once both versions have loaded.

Scrolling and interactions can be mirrored between versions. If the structures or controls differ substantially, inspect each version independently as well.

See [how to compare UI commits](/guides/compare-ui-commits/) for the review workflow, or [troubleshooting](/docs/troubleshooting/) for a version that will not load.

---

Canonical page: https://critter.sh/docs/supported-projects/