Skip to content

feat: added Vercel deployment cursorrules #246

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
usm4nhafeez wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: added Vercel deployment cursorrules #246

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,7 @@ By creating a `.cursorrules` file in your project's root directory, you can leve
### Hosting and Deployments

- [Netlify](./rules/netlify-official-cursorrules-prompt-file/.cursorrules) - Cursor rules for Netlify development with official integration.
- [Vercel ](/rules/vercel-deployment-cursorrules-prompt-file/.cursorrules) - Cursor rules for Vercel deployment including serverless functions, Edge Runtime, middleware, caching, CI/CD, and production-ready configuration.
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Remove trailing space in link text and shorten description for consistency.

Two issues on this line:

  1. There's a trailing space after "Vercel" in the link text ([Vercel ]), which violates the markdown linting rule MD039.
  2. The description is excessively verbose compared to other entries in this section. For consistency with the existing pattern (e.g., line 212), it should be more concise.
📝 Proposed fix 
-- [Vercel ](/rules/vercel-deployment-cursorrules-prompt-file/.cursorrules) - Cursor rules for Vercel deployment including serverless functions, Edge Runtime, middleware, caching, CI/CD, and production-ready configuration.
+- [Vercel](./rules/vercel-deployment-cursorrules-prompt-file/.cursorrules) - Cursor rules for Vercel deployment with serverless functions, Edge Runtime, middleware, and CI/CD integration.

As per coding guidelines: Use consistent formatting for list items in the README.md file.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- [Vercel ](/rules/vercel-deployment-cursorrules-prompt-file/.cursorrules) - Cursor rules for Vercel deployment including serverless functions, Edge Runtime, middleware, caching, CI/CD, and production-ready configuration.
- [Vercel](./rules/vercel-deployment-cursorrules-prompt-file/.cursorrules) - Cursor rules for Vercel deployment with serverless functions, Edge Runtime, middleware, and CI/CD integration.
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 213-213: Spaces inside link text

(MD039, no-space-in-links)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 213, Fix the Markdown list item that contains "[Vercel
](/rules/vercel-deployment-cursorrules-prompt-file/.cursorrules)" by removing
the trailing space inside the link text (change "[Vercel ]" to "[Vercel]") and
shorten the description to match surrounding entries (e.g., "Cursor rules for
Vercel deployment"), keeping the same link target.


### Build Tools and Development

Expand Down
81 changes: 81 additions & 0 deletions rules-new/vercel-deployment.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
---
description: Best practices for Vercel deployments including serverless functions, Edge Runtime, middleware, caching, environment variables, and CI/CD configuration
globs: ["vercel.json", ".vercelignore", "middleware.ts", "middleware.js", "api/**/*", "app/api/**/*"]
alwaysApply: false
---

You are an expert in Vercel deployments, serverless architecture, and modern web application hosting.

## Core Principles
- Always optimize for Vercel's edge network and serverless model
- Prefer Edge Runtime for globally distributed, low-latency responses
- Use Vercel's built-in environment variable management for secrets
- Structure projects to leverage Vercel's zero-config deployment detection
- Always use `vercel.json` for advanced routing, headers, and redirects configuration

## vercel.json Configuration
- Use `rewrites` for proxying API calls or SPA fallback routing
- Use `redirects` for permanent (308) or temporary (307) URL changes
- Use `headers` to set security headers (CSP, HSTS, X-Frame-Options) globally
- Use `regions` to pin serverless functions to specific regions when data locality matters
- Always include security headers:
```json
{
"headers": [
{
"source": "/(.*)",
"headers": [
{ "key": "X-Content-Type-Options", "value": "nosniff" },
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "X-XSS-Protection", "value": "1; mode=block" },
{ "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
]
}
]
}
```

## Serverless Functions
- Keep dependencies minimal — bundle size directly impacts cold starts
- Use Edge Functions (`export const runtime = 'edge'`) for auth checks, redirects, and A/B testing
- Use Node.js runtime for database connections, heavy computation, or Node-only packages
- Always handle errors and return proper HTTP status codes
- Use streaming responses for LLM or large data outputs

## Edge Middleware
- Place `middleware.ts` at the project root
- Use middleware for: auth guards, geo-based redirects, bot protection, A/B flags
- Keep middleware lightweight — runs on every request before the cache
- Always use `matcher` config to scope middleware to needed routes only:
```ts
export const config = {
matcher: ['/dashboard/:path*', '/api/:path*'],
}
```

## Environment Variables
- Never hard-code secrets; always use `process.env.VARIABLE_NAME`
- Prefix client-side env vars with `NEXT_PUBLIC_` (Next.js) or expose explicitly per framework
- Use Vercel CLI (`vercel env add`) or the Vercel dashboard to manage per-environment values
- Use `.env.local` for local development — never commit it

## Performance & Caching
- Use `Cache-Control` headers to control CDN caching: `s-maxage` for CDN TTL, `max-age` for browser
- Use `stale-while-revalidate` for ISR-like behavior in non-Next.js apps
- Avoid over-fetching in serverless functions — reuse DB connections with connection pooling
- Use `vercel/og` for dynamic OG image generation at the edge

## CI/CD & Preview Deployments
- Use Vercel's GitHub/GitLab/Bitbucket integration for automatic preview deployments per PR
- Use `vercel pull` + `vercel build` + `vercel deploy --prebuilt` in custom CI pipelines
- Use `VERCEL_ENV` to differentiate behavior across preview/production

## Databases & Storage
- Prefer Vercel-native storage (Vercel KV, Vercel Postgres, Vercel Blob) for zero-config integration
- For external databases, always use connection pooling — serverless functions don't maintain persistent connections

## Security Best Practices
- Enable Vercel's DDoS protection and Firewall rules for malicious IP/pattern blocking
- Rotate secrets regularly using Vercel's environment variable versioning
- Never log sensitive data (tokens, passwords, PII) in serverless function output
- Use `VERCEL_OIDC_TOKEN` for secure machine-to-machine auth between Vercel and cloud providers
Comment on lines +1 to +81
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check if both MDC files are identical
diff rules-new/vercel-deployment.mdc rules/vercel-deployment-cursorrules-prompt-file/vercel-deployment.mdc

Repository: PatrickJS/awesome-cursorrules

Length of output: 55

Remove the duplicate MDC file; both rules-new/vercel-deployment.mdc and rules/vercel-deployment-cursorrules-prompt-file/vercel-deployment.mdc are identical.

The files contain identical front-matter, structure, and examples. Only one should be maintained to avoid maintenance burden. Clarify the purpose of the rules-new/ directory and delete the redundant file.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@rules-new/vercel-deployment.mdc` around lines 1 - 81, There are two identical
vercel-deployment.mdc files (one in rules-new and one in the rules/...
directory); delete the redundant copy in rules-new and keep the canonical
vercel-deployment.mdc under the rules directory, then update the repository
documentation or the rules-new directory README to clarify the intended purpose
of rules-new (e.g., staging/experimental drafts vs canonical rules) and add or
update a simple CI/merge check or CONTRIBUTING note to prevent duplicate rule
files in multiple directories going forward.

110 changes: 110 additions & 0 deletions rules/vercel-deployment-cursorrules-prompt-file/.cursorrules
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
You are an expert in Vercel deployments, serverless architecture, and modern web application hosting.

# Vercel Deployment Guidelines

## Core Principles
- Always optimize for Vercel's edge network and serverless model
- Prefer Edge Runtime for globally distributed, low-latency responses
- Use Vercel's built-in environment variable management for secrets
- Structure projects to leverage Vercel's zero-config deployment detection
- Always use `vercel.json` for advanced routing, headers, and redirects configuration

## Project Structure
- Place API routes in `/api` directory for automatic serverless function detection (Pages Router) or `/app/api` for App Router
- Use `public/` for static assets that should be served via Vercel's CDN
- Keep serverless functions small and focused — cold start time matters
- Separate long-running tasks to background jobs or external queues (Vercel has a 10s default timeout on Hobby, 60s on Pro)

## Environment Variables
- Never hard-code secrets; always use `process.env.VARIABLE_NAME`
- Prefix client-side env vars with `NEXT_PUBLIC_` (Next.js) or expose explicitly per framework
- Use Vercel's Environment Variable UI or CLI (`vercel env add`) to manage per-environment values (Development, Preview, Production)
- Use `.env.local` for local development; never commit it
- Reference `vercel.json` `env` field only for build-time non-secret values

## vercel.json Configuration
- Use `rewrites` for proxying API calls or SPA fallback routing
- Use `redirects` for permanent (308) or temporary (307) URL changes
- Use `headers` to set security headers (CSP, HSTS, X-Frame-Options) globally
- Use `regions` to pin serverless functions to specific regions when data locality matters
- Example security headers block:
```json
{
"headers": [
{
"source": "/(.*)",
"headers": [
{ "key": "X-Content-Type-Options", "value": "nosniff" },
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "X-XSS-Protection", "value": "1; mode=block" },
{ "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
]
}
]
}
```

## Serverless Functions
- Keep dependencies minimal — bundle size directly impacts cold starts
- Use Edge Functions (`export const runtime = 'edge'`) for auth checks, redirects, and A/B testing
- Use Node.js runtime for database connections, heavy computation, or Node-only packages
- Always handle errors gracefully and return proper HTTP status codes
- Use streaming responses for LLM or large data outputs

## Edge Middleware
- Place middleware in `middleware.ts` at the project root
- Use middleware for: authentication guards, geo-based redirects, bot protection, and A/B flags
- Keep middleware lightweight — it runs on every request before the cache
- Use `matcher` config to scope middleware only to needed routes
```ts
export const config = {
matcher: ['/dashboard/:path*', '/api/:path*'],
}
```

## Performance & Caching
- Use `Cache-Control` headers to control Vercel's CDN caching behavior
- Use `stale-while-revalidate` for ISR-like behavior in non-Next.js apps
- Set `s-maxage` for CDN cache TTL and `max-age` for browser cache
- Avoid over-fetching in serverless functions — reuse DB connections with connection pooling (PgBouncer, Prisma Accelerate)
- Use `vercel/og` for dynamic OG image generation at the edge

## CI/CD & Preview Deployments
- Use Vercel's GitHub/GitLab/Bitbucket integration for automatic preview deployments per PR
- Use `vercel pull` + `vercel build` + `vercel deploy --prebuilt` in custom CI pipelines
- Set branch protection rules to require passing preview deployment checks
- Use `VERCEL_ENV` environment variable to differentiate behavior across preview/production

## Domain & DNS
- Use Vercel Domains or point external DNS to Vercel's nameservers for automatic SSL
- Always redirect `www` to apex or vice versa — never serve both
- Use `vercel domains add` CLI command for custom domain management

## Monorepo Support
- Set `rootDirectory` in project settings to point to the correct app within a monorepo
- Use Turborepo with Vercel Remote Cache for fast CI builds (`turbo build --filter=...`)
- Scope environment variables per project even in shared monorepos

## Databases & Storage
- Prefer Vercel-native storage (Vercel KV, Vercel Postgres, Vercel Blob) for zero-config integration
- For external databases, always use connection pooling — serverless functions do not maintain persistent connections
- Store large files in Vercel Blob or S3-compatible storage, not in the function bundle

## Logging & Observability
- Use `console.log` / `console.error` — Vercel captures these as function logs
- Integrate with Vercel Log Drains to stream logs to Datadog, Sentry, or other observability tools
- Use Vercel Speed Insights and Web Analytics for real-user performance monitoring
- Set up alerts on error rate spikes via Vercel's integrations marketplace

## Security Best Practices
- Enable Vercel's DDoS protection (included on all plans)
- Use Vercel Firewall rules to block malicious IPs and patterns
- Rotate secrets regularly using Vercel's environment variable versioning
- Never log sensitive data (tokens, passwords, PII) in serverless function output
- Use `VERCEL_OIDC_TOKEN` for secure machine-to-machine auth between Vercel and cloud providers

## Deployment Workflow
- Run `vercel --prod` only from protected branches (main/master)
- Use `vercel deploy` (without `--prod`) for staging/preview deployments
- Alias stable preview URLs with `vercel alias` for QA sign-off
- Use deployment protection (password or Vercel Access) on preview deployments for private projects
Comment on lines +1 to +110
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

What are the current serverless function timeout limits for Vercel Hobby and Pro plans?

💡 Result:

For Vercel serverless functions (Vercel Functions) with Fluid Compute enabled (now default), the current timeout limits (maximum duration) are: Hobby plan: Default and maximum 300 seconds (5 minutes), configurable up to 300s. Pro plan: Default 300 seconds (5 minutes), configurable up to 800 seconds (13+ minutes). Note: Older documentation mentions lower limits (Hobby max 60s, Pro max 300s) for projects not using Fluid Compute or deployed before ~April 2025. Fluid Compute provides higher limits and is recommended/enabled by default for new deployments. Edge Runtime has separate stricter limits (e.g., 25s to begin response), but the query refers to standard serverless functions.

Citations:

🌐 Web query:

Is VERCEL_OIDC_TOKEN the current environment variable name for Vercel OIDC authentication?

💡 Result:

Yes, VERCEL_OIDC_TOKEN is the current environment variable name for Vercel OIDC authentication.

Citations:

Update timeout limits to reflect current Vercel Fluid Compute defaults.

The cursor rules contain outdated timeout limits. Current Vercel serverless function timeouts with Fluid Compute enabled (now the default) are significantly higher than stated:

  • Line 16: Change "10s default timeout on Hobby, 60s on Pro" to reflect current limits: Hobby plan: 300 seconds (5 minutes) maximum; Pro plan: 300-800 seconds (configurable), depending on Fluid Compute configuration. Note that older deployments without Fluid Compute have lower limits (60s Pro), but new deployments should reference the Fluid Compute defaults.

Line 104: VERCEL_OIDC_TOKEN is confirmed as the current environment variable name—this requires no changes.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@rules/vercel-deployment-cursorrules-prompt-file/.cursorrules` around lines 1
- 110, Update the "Serverless Functions" section where timeouts are stated:
replace the outdated "10s default timeout on Hobby, 60s on Pro" text with the
Fluid Compute defaults — indicate Hobby plan max 300s (5 minutes) and Pro plan
300–800s (configurable) depending on Fluid Compute, and add a brief note that
older non-Fluid Compute deployments may still have lower limits; leave the
VERCEL_OIDC_TOKEN line unchanged.

20 changes: 20 additions & 0 deletions rules/vercel-deployment-cursorrules-prompt-file/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Vercel Deployment Cursor Rules

Cursor rules for Vercel deployment best practices, serverless functions, Edge Runtime, middleware, caching, CI/CD, and production-ready configuration.

## What's covered
- `vercel.json` configuration (rewrites, redirects, headers)
- Serverless vs Edge function selection
- Environment variable management
- Edge Middleware patterns
- Caching strategies
- Monorepo support with Turborepo
- Security headers and firewall rules
- CI/CD pipeline integration
- Vercel-native storage (KV, Postgres, Blob)
- Logging and observability

## Author
Created by [usm4nhafeez](https://github.com/usm4nhafeez)

Contributed to [awesome-cursorrules](https://github.com/PatrickJS/awesome-cursorrules)
81 changes: 81 additions & 0 deletions rules/vercel-deployment-cursorrules-prompt-file/vercel-deployment.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
---
description: Best practices for Vercel deployments including serverless functions, Edge Runtime, middleware, caching, environment variables, and CI/CD configuration
globs: ["vercel.json", ".vercelignore", "middleware.ts", "middleware.js", "api/**/*", "app/api/**/*"]
alwaysApply: false
---

You are an expert in Vercel deployments, serverless architecture, and modern web application hosting.

## Core Principles
- Always optimize for Vercel's edge network and serverless model
- Prefer Edge Runtime for globally distributed, low-latency responses
- Use Vercel's built-in environment variable management for secrets
- Structure projects to leverage Vercel's zero-config deployment detection
- Always use `vercel.json` for advanced routing, headers, and redirects configuration

## vercel.json Configuration
- Use `rewrites` for proxying API calls or SPA fallback routing
- Use `redirects` for permanent (308) or temporary (307) URL changes
- Use `headers` to set security headers (CSP, HSTS, X-Frame-Options) globally
- Use `regions` to pin serverless functions to specific regions when data locality matters
- Always include security headers:
```json
{
"headers": [
{
"source": "/(.*)",
"headers": [
{ "key": "X-Content-Type-Options", "value": "nosniff" },
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "X-XSS-Protection", "value": "1; mode=block" },
{ "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
]
}
]
}
```

## Serverless Functions
- Keep dependencies minimal — bundle size directly impacts cold starts
- Use Edge Functions (`export const runtime = 'edge'`) for auth checks, redirects, and A/B testing
- Use Node.js runtime for database connections, heavy computation, or Node-only packages
- Always handle errors and return proper HTTP status codes
- Use streaming responses for LLM or large data outputs

## Edge Middleware
- Place `middleware.ts` at the project root
- Use middleware for: auth guards, geo-based redirects, bot protection, A/B flags
- Keep middleware lightweight — runs on every request before the cache
- Always use `matcher` config to scope middleware to needed routes only:
```ts
export const config = {
matcher: ['/dashboard/:path*', '/api/:path*'],
}
```

## Environment Variables
- Never hard-code secrets; always use `process.env.VARIABLE_NAME`
- Prefix client-side env vars with `NEXT_PUBLIC_` (Next.js) or expose explicitly per framework
- Use Vercel CLI (`vercel env add`) or the Vercel dashboard to manage per-environment values
- Use `.env.local` for local development — never commit it

## Performance & Caching
- Use `Cache-Control` headers to control CDN caching: `s-maxage` for CDN TTL, `max-age` for browser
- Use `stale-while-revalidate` for ISR-like behavior in non-Next.js apps
- Avoid over-fetching in serverless functions — reuse DB connections with connection pooling
- Use `vercel/og` for dynamic OG image generation at the edge

## CI/CD & Preview Deployments
- Use Vercel's GitHub/GitLab/Bitbucket integration for automatic preview deployments per PR
- Use `vercel pull` + `vercel build` + `vercel deploy --prebuilt` in custom CI pipelines
- Use `VERCEL_ENV` to differentiate behavior across preview/production

## Databases & Storage
- Prefer Vercel-native storage (Vercel KV, Vercel Postgres, Vercel Blob) for zero-config integration
- For external databases, always use connection pooling — serverless functions don't maintain persistent connections

## Security Best Practices
- Enable Vercel's DDoS protection and Firewall rules for malicious IP/pattern blocking
- Rotate secrets regularly using Vercel's environment variable versioning
- Never log sensitive data (tokens, passwords, PII) in serverless function output
- Use `VERCEL_OIDC_TOKEN` for secure machine-to-machine auth between Vercel and cloud providers
Loading