0
# Framework Integration
1

2
Specialized utilities for framework-specific optimizations including analytics plugin injection, environment variable handling, and build command detection for popular frontend frameworks.
3

4
## Capabilities
5

6
### Gatsby Integration
7

8
Specialized utilities for Gatsby.js applications including Vercel analytics plugin injection and configuration management.
9

10
```typescript { .api }
11
/**
12
 * Injects gatsby-plugin-vercel into Gatsby configuration for analytics tracking
13
 * @param dir - Gatsby project directory path
14
 * @returns Promise that resolves when injection is complete
15
 */
16
function injectVercelAnalyticsPlugin(dir: string): Promise<void>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
// Note: Import path may vary depending on build setup
23
// Internal: import * as GatsbyUtils from './utils/gatsby';
24
// External: import * as GatsbyUtils from '@vercel/static-build/utils/gatsby';
25
import * as GatsbyUtils from '@vercel/static-build/utils/gatsby';
26

27
// Inject Vercel analytics into Gatsby project
28
await GatsbyUtils.injectVercelAnalyticsPlugin("/project/gatsby-site");
29
```
30

31
**Gatsby Analytics Injection Process:**
32

33
1. **Environment Variable Setup**: Sets `GATSBY_VERCEL_ANALYTICS_ID` from `VERCEL_ANALYTICS_ID`
34
2. **Package.json Update**: Adds `gatsby-plugin-vercel` as dependency if not present
35
3. **Configuration Injection**: Modifies or creates `gatsby-config.js` with analytics plugin
36
4. **Backup Creation**: Creates backup of existing configuration as `.js.__vercel_builder_backup__.js`
37

38
**Generated gatsby-config.js:**
39
```javascript
40
const userConfig = require("./gatsby-config.js.__vercel_builder_backup__.js");
41

42
// Prefer default export handling
43
const preferDefault = m => (m && m.default) || m;
44

45
const vercelConfig = Object.assign({}, preferDefault(userConfig));
46
if (!vercelConfig.plugins) {
47
  vercelConfig.plugins = [];
48
}
49

50
// Add Vercel analytics plugin if not already present
51
const hasPlugin = vercelConfig.plugins.find(
52
  (p) => p && (p === "gatsby-plugin-vercel" || p.resolve === "gatsby-plugin-vercel")
53
);
54
if (!hasPlugin) {
55
  vercelConfig.plugins = vercelConfig.plugins.slice();
56
  vercelConfig.plugins.push({
57
    resolve: "gatsby-plugin-vercel",
58
    options: {},
59
  });
60
}
61

62
module.exports = vercelConfig;
63
```
64

65
### Nuxt.js Integration
66

67
Specialized utilities for Nuxt.js applications including web vitals analytics plugin injection.
68

69
```typescript { .api }
70
/**
71
 * Injects @nuxtjs/web-vitals plugin into Nuxt configuration for analytics tracking
72
 * @param dir - Nuxt project directory path  
73
 * @returns Promise that resolves when injection is complete
74
 */
75
function injectVercelAnalyticsPlugin(dir: string): Promise<void>;
76
```
77

78
**Usage Examples:**
79

80
```typescript
81
// Note: Import path may vary depending on build setup
82
// Internal: import * as NuxtUtils from './utils/nuxt';
83
// External: import * as NuxtUtils from '@vercel/static-build/utils/nuxt';
84
import * as NuxtUtils from '@vercel/static-build/utils/nuxt';
85

86
// Inject Vercel analytics into Nuxt project
87
await NuxtUtils.injectVercelAnalyticsPlugin("/project/nuxt-app");
88
```
89

90
**Nuxt Analytics Injection Process:**
91

92
1. **Nuxtrc Configuration**: Updates `.nuxtrc` file with `modules[]` entry for `@nuxtjs/web-vitals`
93
2. **Package.json Update**: Adds `@nuxtjs/web-vitals` as dependency if not present
94
3. **Module Registration**: Uses `rc9` library to safely update configuration
95

96
**Generated .nuxtrc:**
97
```ini
98
modules[]="@nuxtjs/web-vitals"
99
```
100

101
### Framework Detection
102

103
Automatic framework detection system that identifies frameworks based on package.json dependencies and applies appropriate optimizations.
104

105
```typescript { .api }
106
/**
107
 * Detects framework from configuration and package.json dependencies
108
 * @param config - Build configuration with optional framework override
109
 * @param pkg - Package.json contents
110
 * @returns Detected framework object or undefined
111
 */
112
function getFramework(
113
  config: Config | null,
114
  pkg?: PackageJson | null
115
): Framework | undefined;
116

117
interface Framework {
118
  name: string;
119
  slug: string | null;
120
  logo: string;
121
  darkModeLogo?: string;
122
  screenshot?: string;
123
  demo?: string;
124
  tagline?: string;
125
  website?: string;
126
  description: string;
127
  dependency?: string;
128
  sort?: number;
129
  useRuntime?: object;
130
  ignoreRuntimes?: string[];
131
  detectors?: object;
132
  recommendedIntegrations?: any[];
133
  defaultVersion?: string;
134
  settings: {
135
    buildCommand: SettingValue;
136
    devCommand: SettingValue;
137
    installCommand?: SettingValue;
138
    outputDirectory?: SettingValue;
139
  };
140
  defaultRoutes?: Route[] | ((dirPrefix: string) => Promise<Route[]>);
141
  cachePattern?: string | string[];
142
  envPrefix?: string;
143
  getOutputDirName?: (outputDirPrefix: string) => Promise<string>;
144
}
145

146
interface SettingValue {
147
  value: string | null;
148
  placeholder?: string;
149
}
150
```
151

152
**Framework Detection Process:**
153

154
1. **Manual Override**: Check `config.framework` for explicit framework specification
155
2. **Dependency Matching**: Match `package.json` dependencies against known framework patterns
156
3. **Framework Selection**: Return first matching framework from frameworks list
157

158
**Supported Frameworks (examples):**
159
- **Next.js**: `dependency: "next"`
160
- **Create React App**: `dependency: "react-scripts"`  
161
- **Gatsby**: `dependency: "gatsby"`
162
- **Nuxt.js**: `dependency: "nuxt"`
163
- **Vue CLI**: `dependency: "@vue/cli-service"`
164
- **Angular**: `dependency: "@angular/cli"`
165
- **Svelte Kit**: `dependency: "@sveltejs/kit"`
166

167
### Environment Variable Handling
168

169
Framework-specific environment variable injection and prefixing for client-side access.
170

171
**Create React App Integration:**
172
```typescript
173
// Disable CI warnings that fail builds
174
if (framework?.slug === 'create-react-app') {
175
  spawnOpts.env.CI = 'false';
176
}
177
```
178

179
**Framework Prefix Handling:**
180
```typescript
181
// Inject VERCEL_ environment variables with framework prefix
182
if (process.env.VERCEL_URL && framework.envPrefix) {
183
  Object.keys(process.env)
184
    .filter(key => key.startsWith('VERCEL_'))
185
    .forEach(key => {
186
      const newKey = `${framework.envPrefix}${key}`;
187
      if (!(newKey in process.env)) {
188
        process.env[newKey] = process.env[key];
189
      }
190
    });
191
}
192
```
193

194
**Framework Environment Prefixes:**
195
- **Gatsby**: `GATSBY_` - Exposes variables to client-side bundles
196
- **Next.js**: `NEXT_PUBLIC_` - Exposes variables to browser
197
- **Create React App**: `REACT_APP_` - Bundled into client code
198

199
### Build Command Detection
200

201
Intelligent build command detection with framework-specific defaults and package.json script fallbacks.
202

203
```typescript { .api }
204
/**
205
 * Determines appropriate command for install, build, or dev operations
206
 * @param name - Command type (install, build, dev)
207
 * @param pkg - Package.json contents
208
 * @param config - Build configuration
209
 * @param framework - Detected framework
210
 * @returns Command string or null
211
 */
212
function getCommand(
213
  name: 'install' | 'build' | 'dev',
214
  pkg: PackageJson | null,
215
  config: Config,
216
  framework: Framework | undefined
217
): string | null;
218

219
/**
220
 * Gets script name from package.json with fallbacks
221
 * @param pkg - Package.json contents
222
 * @param cmd - Base command name
223
 * @param config - Build configuration
224
 * @returns Script name to execute
225
 */
226
function getScriptName(pkg: PackageJson, cmd: string, config: Config): string;
227

228
/**
229
 * Checks if a script exists in package.json
230
 * @param script - Script name to check
231
 * @param pkg - Package.json contents
232
 * @returns Whether the script exists
233
 */
234
function hasScript(script: string, pkg: PackageJson): boolean;
235
```
236

237
**Command Detection Priority:**
238

239
1. **Explicit Config**: Use `config.buildCommand`, `config.devCommand`, `config.installCommand`
240
2. **Package.json Scripts**: Check for `now-build`, `vercel-build`, `build`, `dev`, `now-dev`
241
3. **Framework Defaults**: Use framework's default build/dev commands
242
4. **Zero Config**: Apply zero-configuration defaults
243

244
**Example Command Resolution:**
245
```typescript
246
// For Next.js framework
247
const buildCommand = getCommand('build', pkg, config, nextjsFramework);
248
// Returns: "next build" (from framework defaults)
249

250
const devCommand = getCommand('dev', pkg, config, nextjsFramework);  
251
// Returns: "next dev" (from framework defaults)
252
```
253

254
### Route Generation
255

256
Framework-specific route generation for single-page applications and static sites.
257

258
```typescript { .api }
259
/**
260
 * Generates framework-specific routes for deployment
261
 * @param framework - Framework configuration
262
 * @param dirPrefix - Directory prefix for routes
263
 * @returns Promise resolving to route array
264
 */
265
async function getFrameworkRoutes(
266
  framework: Framework,
267
  dirPrefix: string
268
): Promise<Route[]>;
269
```
270

271
**Framework Route Examples:**
272

273
**Next.js Routes:**
274
```javascript
275
[
276
  { src: '/api/(.*)', dest: '/api/$1' },
277
  { src: '/((?!api).+)', dest: '/$1.html' },
278
  { src: '/', dest: '/index.html' }
279
]
280
```
281

282
**Gatsby Routes:**
283
```javascript
284
[
285
  { src: '/(.*)', dest: '/$1.html' },
286
  { src: '/', dest: '/index.html' }
287
]
288
```
289

290
### Development Server Integration
291

292
Framework-specific development server handling with port management and proxy configuration.
293

294
**Development Route Generation:**
295
```typescript { .api }
296
/**
297
 * Creates development route for proxying to local dev server
298
 * @param srcBase - Source base path
299
 * @param devPort - Development server port
300
 * @param route - Route configuration
301
 * @returns Route with dev server proxy destination
302
 */
303
const getDevRoute = (srcBase: string, devPort: number, route: RouteWithSrc): RouteWithSrc;
304
```
305

306
**Development Flow:**
307
1. Start framework's dev server on available port
308
2. Wait for server to become reachable
309
3. Generate proxy routes to development server
310
4. Handle process cleanup on termination
311

312
**Example Dev Route:**
313
```javascript
314
{
315
  src: '/(.*)',
316
  dest: 'http://localhost:3000/$1'
317
}
318
```