Using .vercelignore

A .vercelignore file tells Vercel which files and folders should be excluded from deployments. It is useful when a repository contains local notes, heavy raw assets, screenshots, test fixtures, exports, or other files that do not belong in the deployed build context. Used well, it keeps deployments smaller, cleaner, and less surprising. Used badly, it can create a false sense of security.

The most important warning is this: .vercelignore is not secret management. Secrets should not be committed to the repository in the first place. If a file contains API keys, production credentials, private customer data, database dumps, or certificates, the solution is to remove it from Git and rotate anything exposed. Adding it to .vercelignore after committing it does not erase Git history or remove it from every clone and integration.

This lesson teaches .vercelignore as a deployment hygiene tool, not as a vault.

What .vercelignore Does

When Vercel prepares a deployment, it gathers files from the project. A .vercelignore file can exclude matching paths from that deployment process. The syntax is similar in spirit to ignore files many developers already know: list files, folders, or patterns that should be skipped.

A simple example:

# .vercelignore
notes/
raw-assets/
exports/
*.psd
*.zip
local-screenshots/

Those patterns say that the listed directories and file types are not needed by Vercel. The deployment should not upload them as part of the project context.

This can matter for speed, clarity, and accidental exposure. If a folder contains large Photoshop files, old exports, or scratch notes, Vercel does not need them to build a static site or frontend app. Excluding them makes the deployment input easier to reason about.

.gitignore Vs .vercelignore

.gitignore and .vercelignore solve different problems.

.gitignore tells Git which untracked local files should not be added to the repository. It is about source control.

.vercelignore tells Vercel which repository files or local files should not be included in the deployment. It is about deployment input.

The difference matters:

Ignored by .gitignore
  not committed to Git if never added
  not visible to normal Git clones
  may still exist on your machine

Ignored by .vercelignore
  may still be committed to Git
  may still be visible on GitHub
  skipped by Vercel deployment collection

If a secret is already committed, .vercelignore is too late. The secret is in Git. Treat it as exposed, rotate it, and remove it properly.

A healthy project often uses both files:

.gitignore
  .env.local
  node_modules/
  build caches
  editor temporary files

.vercelignore
  local notes
  raw source assets not needed for build
  test fixtures not needed in deployment
  large exports or screenshots

Do not blindly copy every .gitignore entry into .vercelignore. Some files ignored by Git may be generated during build and irrelevant to upload. Some committed files may be necessary for build even if they are not public assets.

What To Exclude

Good .vercelignore entries are files that are safe in the repository but unnecessary for deployment.

Examples include:

notes/
design-drafts/
raw-assets/
local-screenshots/
review-recordings/
exports/
coverage/
*.zip
*.psd
*.sketch
*.sqlite

Be careful with test fixtures. Some projects need fixtures during build, static generation, or integration tests. Others do not. If tests run in a separate CI system before Vercel builds, fixtures may not need to be uploaded to Vercel. If the Vercel build runs checks that need fixtures, excluding them can break the build.

Be careful with documentation too. A documentation site may need Markdown files to generate pages. A frontend app may not need internal contributor notes. The right choice depends on the build process.

The decision test is:

Does the build need this file?
Does runtime server-side code need this file?
Is this file safe to keep in Git?
Would excluding it make deployment smaller or safer?

Only exclude it when the answers make sense together.

What Not To Use It For

Do not use .vercelignore as your main protection for sensitive files.

Bad pattern:

# Bad idea
.env.production
customer-export.csv
private-key.pem

Those files should not be committed. If they are in the repository, collaborators and Git integrations may already see them. Vercel ignoring them during deployment does not fix the exposure.

A better pattern is:

.env.example       committed, placeholders only
.env.local         ignored by Git
production secrets stored in Vercel Environment Variables
customer exports stored in protected systems
private keys stored in a proper secret manager

Use .vercelignore for unnecessary deployment files. Use .gitignore and secret-management habits to keep sensitive files out of source control. Use Vercel Environment Variables for deployment secrets.

Example For A Static Site

For the plain static site from earlier lessons, the repository might contain a few extra local files:

index.html
styles.css
app.js
README.md
notes/
raw-assets/
screenshots/

The deployed site only needs index.html, styles.css, and app.js. The README is harmless, but not necessary. The notes and raw assets may be unnecessary.

A reasonable .vercelignore might be:

notes/
raw-assets/
screenshots/

You may keep README.md in the deployment input because it is tiny and harmless, or exclude it if you prefer a cleaner upload:

README.md

Either choice is fine if the file does not affect the build. The important part is understanding why each pattern exists.

Example For A Vite App

A Vite app might look like this:

package.json
src/
public/
design/
coverage/
test-fixtures/
raw-images/

The build likely needs package.json, source files, and public assets. It probably does not need coverage output, raw design images, or local design drafts.

A possible .vercelignore:

coverage/
design/
raw-images/

Do not exclude src/, public/, package.json, lock files, or configuration needed by the build. If the build fails after adding .vercelignore, check whether you excluded something the build actually reads.

Example For A Full-Stack App

A full-stack app may have server-side code, API routes, database schemas, migration files, and framework configuration. Excluding files is riskier because runtime code may depend on files that are not obvious from the browser output.

Before adding broad patterns, ask:

Do serverless functions import this folder?
Does static generation read these files?
Do migrations run during deployment?
Does the framework trace this file automatically?
Are tests or checks run during Vercel build?

Avoid broad patterns such as:

config/
data/
lib/
scripts/

Those names are too likely to contain real application dependencies. Prefer precise patterns:

local-notes/
manual-test-recordings/
raw-import-samples/

A deployment ignore file should reduce clutter, not hide uncertainty.

When Not To Add A Pattern Yet

If you are unsure whether a file is needed, do not immediately ignore it. First identify which step might use it. A build command may read configuration, content files, schema files, generated clients, or framework metadata. A serverless function may import files that are not visible from the homepage. Static generation may read Markdown, JSON, images, or route data at build time.

A cautious workflow is to add one ignore pattern at a time, deploy, and verify. If a broad cleanup excludes ten folders at once and the build fails, you have created a harder debugging problem. Small changes produce clearer evidence. This is especially important in monorepos, where one folder may look unrelated but be imported by a shared package or build script.

If the repository contains messy files and you cannot tell what is needed, the better first step may be reorganizing the project. Move local-only material into clearly named folders such as local-notes/ or raw-design-assets/, then ignore those folders. Do not use complicated ignore rules to compensate for an unclear repository layout.

Test The Result

After changing .vercelignore, create a deployment and inspect the build result. If the build fails, read the first meaningful error. Missing file errors often point directly to an over-broad ignore pattern.

A short check is:

Deployment starts.
Install step can read package files.
Build step can read source and config.
Generated output contains expected assets.
Runtime routes still work.
Unneeded large files are absent from deployment input.
No secrets were committed as a workaround.

If you are unsure whether a file is included, test with a harmless marker file in a non-production project, or inspect build behavior. Do not test with real secrets.

Keep The File Reviewable

A .vercelignore file should be understandable in code review. Add a short comment when a pattern is not obvious:

# Large source images are processed before commit; deployment uses public/optimized/.
raw-images/

# Local QA recordings are not used by the build.
qa-recordings/

Avoid clever ignore patterns that future maintainers cannot safely change. If a pattern excludes many file types, explain why. If a folder name is broad, prefer a narrower folder name instead of relying on comments to prevent mistakes.

Reviewing Ignore Changes In Pull Requests

Treat changes to .vercelignore as deployment changes, not as harmless housekeeping. A one-line ignore pattern can remove a file that production needs. In code review, ask what problem the pattern solves, whether the file is safe to keep in Git, and whether the build or runtime depends on it.

A reviewer should be especially careful with patterns that hide whole directories. Names such as data/, config/, scripts/, and fixtures/ are ambiguous. They might contain local junk, but they might also contain content, generated clients, schema definitions, migration helpers, or build-time inputs. If the folder has mixed responsibilities, split it before ignoring it.

Also review what the ignore file does not solve. If the pull request adds .vercelignore because a sensitive file was accidentally committed, the review should require secret rotation and repository cleanup. The ignore file may still be useful afterward, but it is not the security fix. Clear review questions keep the team from turning deployment hygiene into a place where exposure incidents are quietly buried.

Common Mistakes

The first mistake is treating .vercelignore as a place to hide secrets. It is not.

The second mistake is excluding files the build needs. If the build reads a folder, do not ignore it.

The third mistake is copying .gitignore without thinking. Deployment and source control are related but different workflows.

The fourth mistake is ignoring too broadly. A pattern such as data/ might remove local junk or might remove production data files needed at build time.

The fifth mistake is never reviewing the file again. As the project changes, old ignore patterns may become wrong.

The sixth mistake is assuming .vercelignore controls what browser users can request. Public output, framework routing, and asset directories still determine URLs.

Review Questions

What problem does .vercelignore solve?
How is .vercelignore different from .gitignore?
Why is .vercelignore not secret management?
What kinds of files are good candidates for exclusion?
Why can broad ignore patterns break full-stack builds?
What should you check after changing .vercelignore?