> Meticulous records real user sessions from a web app and replays them against each commit to catch visual regressions.
>
> Full AI-readable docs index (complete project setup journey + every page as markdown): https://app.meticulous.ai/llms.txt
# Vue 3 with Vite - Complete Setup Guide
Complete guide for setting up Meticulous with Vue 3 applications built with Vite.
---
## Overview
Vue 3 with Vite provides a fast development experience. This guide covers:
- **Recorder installation** in `index.html`
- **CI/CD configuration** with static asset upload
- **Authentication handling**
- **Common patterns** and troubleshooting
**Prerequisites**:
- Vue 3 application using Vite
- Basic familiarity with [Meticulous concepts](/docs/onboarding-guide)
---
## Quick Start
### Step 1: Install Recorder in index.html
Add the Meticulous recorder script to your `index.html` **before any other scripts**.
**File**: `index.html`
```html
Your App Name
```
**Important**: The recorder must load before your application code.
---
### Step 2: Configure GitHub Actions Workflow
Vue/Vite builds to static files, so we use the `upload-assets` action.
**File**: `.github/workflows/meticulous.yml`
```yaml
name: Meticulous
# Important: The workflow needs to run both on pushes to your main branch and on
# pull requests. It needs to run on your main branch because it'll use the results
# from the base commit of the PR on the main branch to compare against.
on:
push:
branches:
- main
pull_request: {}
# Important: We need the workflow to be triggered on workflow_dispatch events,
# so that Meticulous can run the workflow on the base commit to compare
# against if an existing workflow hasn't run. The meticulous-commit-sha input
# lets Meticulous ask for a specific commit (e.g. stacked PRs); without it,
# a dispatched run can only build whatever the branch currently points at.
workflow_dispatch:
inputs:
meticulous-commit-sha:
description: Commit Meticulous has asked this run to build. Defaults to the branch head.
required: false
# Important: The workflow needs all the permissions below.
# These permissions are mainly needed to post and update the status check and
# feedback comment on your PR. Meticulous won't work without them.
permissions:
actions: write
contents: read
issues: write
pull-requests: write
statuses: read
env:
# Prefer the dispatched commit when set; otherwise the PR head. On pull_request github.sha is the merge commit,
# not the PR head SHA that Meticulous looks up.
METICULOUS_COMMIT_SHA: ${{ github.event.inputs['meticulous-commit-sha'] || (github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha) }}
jobs:
test:
name: Meticulous
runs-on: ubuntu-latest
steps:
# Same workflow file as the upload step — ensure-base dispatches *this*
# workflow on the base branch. Run it before checkout/build so the base
# can start while this job continues. Needs no checkout. Pass the same
# ref as checkout so we pre-warm the base the upload step will ask for.
- name: Ensure base tests exist
uses: alwaysmeticulous/report-diffs-action/ensure-base@v1
with:
api-token: ${{ secrets.METICULOUS_API_TOKEN }}
ref: ${{ env.METICULOUS_COMMIT_SHA }}
- name: Checkout repository
uses: actions/checkout@v4
with:
ref: ${{ env.METICULOUS_COMMIT_SHA }}
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build app
run: npm run build
env:
NODE_ENV: production
- name: Upload and test
uses: alwaysmeticulous/report-diffs-action/upload-assets@v1
with:
api-token: ${{ secrets.METICULOUS_API_TOKEN }}
app-directory: "dist"
rewrites: |
[
{ "source": "/(.*)", "destination": "/index.html" }
]
```
---
### Step 3: Add API Token Secret
1. Get your API token from [Meticulous dashboard](https://app.meticulous.ai) → Project Settings
2. Go to GitHub repo → Settings → Secrets and variables → Actions
3. Create secret named `METICULOUS_API_TOKEN` with your token
---
## How It Works
### upload-assets Action
The `upload-assets` action uploads your built files and runs tests against them.
**Build output**: Vite builds to `dist/` directory by default.
### Rewrites Configuration
Handles client-side routing (Vue Router):
```json
[
{ "source": "/(.*)", "destination": "/index.html" }
]
```
---
## Common Patterns
### Pattern 1: Detect Test Mode
Use `window.Meticulous.isRunningAsTest` in your components:
**Options API**:
```vue
```
---
## CI/CD Configuration Details
### Environment Variables
Vite exposes environment variables prefixed with `VITE_`:
```yaml
- name: Build app
run: npm run build
env:
VITE_API_URL: "https://api.example.com"
VITE_APP_NAME: "My App"
NODE_ENV: production
```
**In code**:
```typescript
const apiUrl = import.meta.env.VITE_API_URL
```
### TypeScript Configuration
Ensure TypeScript recognizes Vite env variables:
**File**: `src/env.d.ts`
```typescript
///
interface ImportMetaEnv {
readonly VITE_API_URL: string
readonly VITE_APP_NAME: string
}
interface ImportMeta {
readonly env: ImportMetaEnv
}
```
---
## Troubleshooting
### Issue: Recorder Not Loading
**Symptom**: `window.Meticulous` is undefined
**Checks**:
1. Verify recorder script in `index.html` ``
2. Check project ID is correct
3. Check for CSP blocking
**Fix**: Ensure correct placement:
```html
Your App
```
---
### Issue: Routes Return 404
**Symptom**: Direct navigation to routes returns 404
**Cause**: Missing rewrite configuration
**Fix**:
```yaml
rewrites: |
[
{ "source": "/(.*)", "destination": "/index.html" }
]
```
---
### Issue: TypeScript Errors
**Symptom**: `Property 'Meticulous' does not exist on type 'Window'.`
**Fix**: Add type declarations
**File**: `src/types/meticulous.d.ts`
```typescript
interface Meticulous {
isRunningAsTest?: boolean
recordCustomValues?: (values: Record) => void
getCustomValues?: () => Record | undefined
pause?: () => void
resume?: () => void
}
declare global {
interface Window {
Meticulous?: Meticulous
}
}
export {}
```
---
### Issue: False Positive Diffs
**Common causes**:
1. Animations not completing
2. Random data
3. Timestamps
**Fixes**:
**Disable animations in tests**:
```vue
Content
```
**Deterministic IDs**:
```typescript
const generateId = () => {
if (window.Meticulous?.isRunningAsTest) {
return 'test-id-12345'
}
return crypto.randomUUID()
}
```
**Ignore timestamps**:
```vue
{{ new Date().toLocaleString() }}
```
Learn more: [Fix False Positive Diffs](/docs/how-to/fix-false-positive-diffs)
---
## Testing Best Practices
### 1. Handle Loading States
Always show loading states:
```vue
```
### 2. Use Suspense for Async Components
```vue
```
### 3. Test Locally First
```bash
# Build your app
npm run build
# Serve built files
npx serve dist
# Verify at http://localhost:3000
```
---
## Advanced Configuration
### Monorepo Setup
```yaml
- name: Install dependencies
working-directory: ./apps/frontend
run: npm ci
- name: Build app
working-directory: ./apps/frontend
run: npm run build
- name: Upload and test
uses: alwaysmeticulous/report-diffs-action/upload-assets@v1
with:
api-token: ${{ secrets.METICULOUS_API_TOKEN }}
app-directory: "./apps/frontend/dist"
rewrites: |
[
{ "source": "/(.*)", "destination": "/index.html" }
]
```
### Custom Vite Config
**File**: `vite.config.ts`
```typescript
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import CssSourcemapPlugin from '@alwaysmeticulous/recorder-plugin/css-sourcemap'
export default defineConfig({
plugins: [vue(), CssSourcemapPlugin()],
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url))
}
},
build: {
outDir: 'dist',
sourcemap: true
}
})
```
**Important**: `build.sourcemap` covers JavaScript only — it does nothing for CSS. Vite emits no CSS source maps for
production builds at all, so without extra help Meticulous cannot attribute stylesheet coverage back to the files in your repo.
`@alwaysmeticulous/recorder-plugin/css-sourcemap` emits a `.css.map` for each CSS asset to close that gap.
The plugin disables Vite's CSS minification, which is what makes the maps accurate, so enable it on the build whose coverage
Meticulous collects rather than on every production build. See
[Viewing source coverage information](/docs/how-to/enable-source-coverage) for the accuracy details and the full set of options.
---
## See Also
- [Onboarding Guide](/docs/onboarding-guide) - General Meticulous setup
- [Troubleshoot Authentication](/docs/how-to/troubleshoot-auth) - Auth patterns and solutions
- [Fix False Positives](/docs/how-to/fix-false-positive-diffs) - Handle non-deterministic content