Skip to content

Commit 1220921

Browse files
s00ds00d
committed
feat(docs): add guide for excluding static files from i18n routing
1 parent 83467a6 commit 1220921

2 files changed

Lines changed: 183 additions & 0 deletions

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ export default defineConfig({
4141
{ text: 'Testing', link: '/guide/testing' },
4242
{ text: 'Storybook', link: '/guide/storybook' },
4343
{ text: 'Custom Auto Detect', link: '/guide/custom-auto-detect' },
44+
{ text: 'Excluding Static Files', link: '/guide/excluding-static-files' },
4445
{ text: 'CLI Tool', link: '/guide/cli' },
4546
],
4647
},
@@ -114,6 +115,7 @@ export default defineConfig({
114115
{ text: 'Testing', link: '/testing' },
115116
{ text: 'Storybook', link: '/storybook' },
116117
{ text: 'Custom Auto Detect', link: '/custom-auto-detect' },
118+
{ text: 'Excluding Static Files', link: '/excluding-static-files' },
117119
{ text: 'CLI Tool', link: '/cli' },
118120
],
119121
},

‎docs/guide/excluding-static-files.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Excluding Static Files from i18n Routing
2+
3+
## Overview
4+
5+
By default, nuxt-i18n-micro automatically excludes common static files from i18n routing processing. However, you can also configure custom exclusion patterns to prevent specific paths from being processed by the i18n system.
6+
7+
## Built-in Exclusions
8+
9+
The module automatically excludes the following file types and patterns:
10+
11+
- **Sitemaps**: `/sitemap*.xml`, `/sitemap-en.xml`, etc.
12+
- **SEO files**: `/robots.txt`, `/favicon.ico`
13+
- **PWA files**: `/manifest.json`, `/sw.js`, `/workbox-*.js`
14+
- **Static assets**: Files with extensions like `.xml`, `.txt`, `.ico`, `.json`, `.js`, `.css`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.woff`, `.woff2`, `.ttf`, `.eot`
15+
- **Internal Nuxt paths**: Any path starting with `__` (like `/__nuxt/`)
16+
17+
## Custom Exclusion Patterns
18+
19+
You can define custom exclusion patterns using the `excludePatterns` option:
20+
21+
```typescript
22+
// nuxt.config.ts
23+
export default defineNuxtConfig({
24+
modules: ['nuxt-i18n-micro'],
25+
26+
i18n: {
27+
locales: [
28+
{ code: 'en', iso: 'en-US' },
29+
{ code: 'it', iso: 'it-IT' }
30+
],
31+
defaultLocale: 'en',
32+
33+
// Custom exclusion patterns
34+
excludePatterns: [
35+
// String patterns (exact match or prefix)
36+
'/api/health',
37+
'/admin',
38+
39+
// String patterns with wildcards
40+
'/api/*',
41+
'/admin/**',
42+
43+
// Regular expressions
44+
/^\/api\/v\d+\//,
45+
/\.(pdf|doc|docx)$/,
46+
]
47+
}
48+
})
49+
```
50+
51+
## Pattern Types
52+
53+
### String Patterns
54+
55+
- **Exact match**: `'/api/health'` - matches exactly `/api/health`
56+
- **Prefix match**: `'/admin'` - matches `/admin` and `/admin/dashboard`
57+
- **Wildcards**: `'/api/*'` - matches `/api/users` but not `/api/users/123`
58+
- **Deep wildcards**: `'/admin/**'` - matches `/admin/users` and `/admin/users/123`
59+
60+
### Regular Expressions
61+
62+
Use RegExp objects for complex pattern matching:
63+
64+
```typescript
65+
excludePatterns: [
66+
/^\/api\/v\d+\//, // API versioned routes
67+
/\.(pdf|doc|docx)$/, // Document files
68+
/^\/static\//, // Static directory
69+
/^\/[a-z]{2}\/api\//, // Localized API routes
70+
]
71+
```
72+
73+
## Use Cases
74+
75+
### SEO Files
76+
```typescript
77+
excludePatterns: [
78+
'/sitemap.xml',
79+
'/sitemap-*.xml',
80+
'/robots.txt',
81+
'/favicon.ico'
82+
]
83+
```
84+
85+
### API Routes
86+
```typescript
87+
excludePatterns: [
88+
'/api/**',
89+
'/graphql',
90+
'/webhook/**'
91+
]
92+
```
93+
94+
### Admin Panels
95+
```typescript
96+
excludePatterns: [
97+
'/admin',
98+
'/admin/**',
99+
'/dashboard'
100+
]
101+
```
102+
103+
### Static Assets
104+
```typescript
105+
excludePatterns: [
106+
'/assets/**',
107+
'/static/**',
108+
'/uploads/**'
109+
]
110+
```
111+
112+
## How It Works
113+
114+
1. **Server Middleware**: A Nitro middleware runs first to check exclusion patterns
115+
2. **Page Processing**: During page resolution, excluded paths are skipped
116+
3. **Catch-all Route**: The fallback route checks exclusions before processing
117+
4. **Prerendering**: Excluded paths are not included in prerendered routes
118+
119+
## Performance Impact
120+
121+
- Exclusion checks are optimized and run early in the request lifecycle
122+
- Built-in patterns use efficient regex matching
123+
- Custom patterns are cached and reused
124+
- Minimal performance overhead for excluded paths
125+
126+
## Troubleshooting
127+
128+
### Static Files Still Being Intercepted
129+
130+
1. **Check pattern syntax**: Ensure your patterns match the exact path structure
131+
2. **Use regex for complex patterns**: String wildcards have limitations
132+
3. **Test patterns**: Use browser dev tools to verify the actual request path
133+
4. **Check order**: Ensure exclusion patterns are defined before other i18n config
134+
135+
### Pattern Not Working
136+
137+
```typescript
138+
// ❌ Wrong - this won't work
139+
excludePatterns: ['sitemap.xml']
140+
141+
// ✅ Correct - include leading slash
142+
excludePatterns: ['/sitemap.xml']
143+
144+
// ✅ Better - use regex for flexibility
145+
excludePatterns: [/^\/sitemap.*\.xml$/]
146+
```
147+
148+
### Debug Mode
149+
150+
Enable debug mode to see exclusion processing:
151+
152+
```typescript
153+
i18n: {
154+
debug: true,
155+
excludePatterns: ['/api/**']
156+
}
157+
```
158+
159+
This will log exclusion decisions in the console.
160+
161+
## Migration from Workarounds
162+
163+
If you were using workarounds like route rules or middleware, you can now replace them with `excludePatterns`:
164+
165+
```typescript
166+
// ❌ Old workaround
167+
export default defineNuxtConfig({
168+
routeRules: {
169+
'/sitemap*.xml': { headers: { 'content-type': 'application/xml' } }
170+
}
171+
})
172+
173+
// ✅ New approach
174+
export default defineNuxtConfig({
175+
i18n: {
176+
excludePatterns: ['/sitemap*.xml']
177+
}
178+
})
179+
```
180+
181+
The new approach is more reliable and works at multiple levels of the routing system.

0 commit comments

Comments
 (0)