@agility/create-next-app 1.0.0-beta.2

package/templates/docs/README.md

@@ -0,0 +1,164 @@
+# Agility CMS + Next.js Documentation
+
+Complete documentation for building websites with Agility CMS and Next.js. Optimized for both human developers and AI coding assistants.
+
+## Quick Start
+
+1. **[01-agility-cms-overview.md](./01-agility-cms-overview.md)** - Understand how Agility CMS works
+2. **[03-creating-components.md](./03-creating-components.md)** - Create your first module
+3. **[08-common-components.md](./08-common-components.md)** - See production-ready examples
+
+## 📚 Documentation Index
+
+### Core Concepts
+- **[01-agility-cms-overview.md](./01-agility-cms-overview.md)** - How Agility CMS works with Next.js
+- **[02-page-routing.md](./02-page-routing.md)** - Dynamic routing, URLs, and the proxy
+
+### Development Guide
+- **[03-creating-components.md](./03-creating-components.md)** - Build module components step-by-step
+- **[04-data-fetching.md](./04-data-fetching.md)** - Fetch content from Agility CMS
+- **[05-containers-and-lists.md](./05-containers-and-lists.md)** - Work with content lists (blogs, testimonials, etc.)
+- **[08-common-components.md](./08-common-components.md)** - Production-ready component examples
+
+### Advanced Features
+- **[06-localization.md](./06-localization.md)** - Multi-language support
+- **[07-caching-strategies.md](./07-caching-strategies.md)** - Performance and caching
+- **[11-linked-nested-content.md](./11-linked-nested-content.md)** - Linked and nested content patterns
+
+### Setup & Configuration
+- **[10-mcp-server-setup.md](./10-mcp-server-setup.md)** - Connect AI assistants to Agility CMS via MCP
+- **[09-whats-included.md](./09-whats-included.md)** - Feature checklist
+
+## 🎯 Common Tasks
+
+### Add a Blog
+1. Read [05-containers-and-lists.md](./05-containers-and-lists.md)
+2. Create PostListing component using examples
+3. Configure "posts" content list in Agility CMS
+4. Add content and it renders automatically
+
+### Add a Hero Section
+1. See examples in [08-common-components.md](./08-common-components.md)
+2. Copy Hero component code
+3. Register in `components/agility-components/index.ts`
+4. Create Hero module in Agility CMS
+
+### Enable Multi-Language
+1. Read [06-localization.md](./06-localization.md)
+2. Update `AGILITY_LOCALES` environment variable
+3. Update `lib/i18n/config.ts` with new locales
+4. Add locale-specific content in Agility CMS
+
+### Optimize Performance
+1. Read [07-caching-strategies.md](./07-caching-strategies.md)
+2. Configure revalidation time in page routes
+3. Set up webhooks for on-demand revalidation
+4. Monitor and debug cache behavior
+
+## 🏗️ Project Architecture
+
+```
+/
+├── app/
+│   └── [locale]/
+│       ├── [...slug]/
+│       │   └── page.tsx           # All pages route here
+│       └── layout.tsx
+├── components/
+│   ├── agility-components/        # CMS modules (Hero, Blog, etc.)
+│   │   ├── index.ts               # Component registry
+│   │   ├── RichTextArea.tsx
+│   │   └── ...
+│   └── agility-pages/             # Page templates
+│       ├── index.ts               # Template registry
+│       ├── MainTemplate.tsx
+│       └── ...
+├── lib/
+│   ├── cms/                       # CMS helper functions
+│   │   ├── getAgilityPage.ts     # Fetch page with modules
+│   │   ├── getContentItem.ts     # Fetch single item
+│   │   ├── getContentList.ts     # Fetch list of items
+│   │   └── ...
+│   └── i18n/
+│       └── config.ts              # Locale configuration
+├── proxy.ts                        # Routing proxy (Next.js 16+)
+└── docs/                          # This documentation
+```
+
+## 🔑 Key Concepts
+
+### Modules
+Reusable components that content editors add to pages in Agility CMS.
+- Examples: Hero, PostListing, Testimonials, ContactForm
+- Stored in: `components/agility-components/`
+- Registered in: `components/agility-components/index.ts`
+
+### Page Templates
+Define the layout structure of pages. Each template has named content zones where modules can be placed.
+- Stored in: `components/agility-pages/`
+- Registered in: `components/agility-pages/index.ts`
+
+### Content Lists
+Collections of structured content items (posts, team members, testimonials).
+- Defined in Agility CMS
+- Fetched with `getContentList()`
+- Can be filtered, sorted, and paginated
+
+### Locales
+Multi-language support with clean URLs.
+- Default locale has no prefix: `/about`
+- Other locales use prefix: `/fr/about`, `/es/about`
+- Configured in: `lib/i18n/config.ts`
+
+### Caching
+Automatic caching with Next.js Data Cache.
+- Time-based revalidation (ISR)
+- On-demand revalidation via webhooks
+- Cache tags for targeted updates
+
+## 🛠️ CMS Helper Functions
+
+| Function | Purpose | Example |
+|----------|---------|---------|
+| `getAgilityPage()` | Fetch complete page with modules | Page routes |
+| `getContentItem()` | Fetch single content item | Module component |
+| `getContentList()` | Fetch collection of items | Blog listing |
+| `getSitemapFlat()` | Fetch flat sitemap | Navigation |
+| `getSitemapNested()` | Fetch hierarchical sitemap | Breadcrumbs |
+
+## 🤖 For AI Coding Assistants
+
+This documentation enables AI tools to:
+- ✅ Generate production-ready components following established patterns
+- ✅ Fetch content correctly with proper TypeScript types
+- ✅ Handle locales, caching, and routing automatically
+- ✅ Create maintainable, type-safe code
+- ✅ Connect to Agility CMS via MCP server (optional)
+
+**AI-Specific Guide**: See [../.claude/agents.md](../.claude/agents.md)
+
+## 📖 Documentation Philosophy
+
+1. **Example-Driven** - Lots of copy-paste ready code
+2. **Pattern-Based** - Consistent patterns throughout
+3. **Production-Ready** - Real-world examples that work
+4. **Type-Safe** - TypeScript types in all examples
+
+## ✅ Success Metrics
+
+You know the docs are working when:
+- You can build features without checking other files
+- Generated code follows existing patterns
+- TypeScript types are always included
+- CMS integration "just works"
+
+## 🔗 Related Documentation
+
+- **[../.claude/agents.md](../.claude/agents.md)** - Guide for AI coding assistants
+- **[../.claude/QUICK-START.md](../.claude/QUICK-START.md)** - 5-minute quick start
+- **[../DEVELOPMENT.md](../DEVELOPMENT.md)** - Development workflow
+- **[../README.md](../README.md)** - Project overview
+
+---
+
+**Need help?** Start with [01-agility-cms-overview.md](./01-agility-cms-overview.md) or jump to [08-common-components.md](./08-common-components.md) for examples. 🚀

package/templates/lib/cms/getAgilityContext.ts

@@ -0,0 +1,28 @@
+import { draftMode } from 'next/headers';
+import { agilityConfig } from "@agility/nextjs"
+import { type Locale, defaultLocale, isValidLocale, locales } from "@/lib/i18n/config"
+
+/**
+ * Gets the Agility context for the current request.
+ */
+export const getAgilityContext = async (locale?: string) => {
+	//determine if we're in preview mode based on "draft" mode from next.js
+	const { isEnabled } = await draftMode()
+
+	const isDevelopmentMode = process.env.NODE_ENV === "development"
+
+	//determine whether it's preview or dev mode
+	const isPreview = isEnabled || isDevelopmentMode
+
+	// Validate and use the provided locale, fallback to default
+	const validatedLocale: Locale = (locale && isValidLocale(locale, locales)) ? locale : defaultLocale
+
+	return {
+		locales: agilityConfig.locales,
+		locale: validatedLocale,
+		sitemap: agilityConfig.channelName,
+		isPreview,
+		isDevelopmentMode
+	}
+}
+

package/templates/lib/cms/getAgilityPage.ts

@@ -0,0 +1,51 @@
+import "server-only";
+import { getAgilityPageProps } from "@agility/nextjs/node";
+import { getAgilityContext } from "./getAgilityContext";
+
+export interface PageProps {
+	params: Promise<{ slug: string[], locale: string }>
+	searchParams?: Promise<{ [key: string]: string | string[] | undefined }>
+}
+
+/**
+ * Get a page with caching information added.
+ */
+export const getAgilityPage = async ({ params }: PageProps) => {
+	const awaitedParams = await params
+	const { isPreview: preview, locale } = await getAgilityContext(awaitedParams.locale)
+
+	if (!awaitedParams.slug) awaitedParams.slug = [""]
+
+	//check the last element of the slug to see if it has search params encoded (from middleware)
+	let lastSlug = awaitedParams.slug[awaitedParams.slug.length - 1]
+	let searchParams: { [key: string]: string } = {}
+	if (lastSlug && lastSlug.startsWith("~~~") && lastSlug.endsWith("~~~")) {
+		//we have search params encoded here
+		lastSlug = lastSlug.replace(/~~~+/g, "")
+		const decoded = decodeURIComponent(lastSlug)
+		const parts = decoded.split("&").map(part => part.trim())
+
+		parts.forEach(part => {
+			const kvp = part.split("=")
+			if (kvp.length === 2) {
+				searchParams[kvp[0]] = kvp[1]
+			}
+		})
+
+		awaitedParams.slug = awaitedParams.slug.slice(0, awaitedParams.slug.length - 1)
+		if (awaitedParams.slug.length === 0) awaitedParams.slug = [""]
+	}
+
+	//get the page
+	const page = await getAgilityPageProps({
+		params: awaitedParams, preview, locale, apiOptions: {
+			contentLinkDepth: 0
+		}
+	})
+
+	page.globalData = page.globalData || {};
+	page.globalData["searchParams"] = searchParams;
+
+	return page
+}
+

package/templates/lib/cms/getAgilitySDK.ts

@@ -0,0 +1,22 @@
+import "server-only";
+
+import agility from '@agility/content-fetch'
+import { draftMode } from 'next/headers';
+
+const getAgilitySDK = async () => {
+	//get the preview data
+	const isDevelopmentMode = process.env.NODE_ENV === "development"
+	const { isEnabled: isDraftMode } = await draftMode()
+	const isPreview = isDevelopmentMode || isDraftMode
+
+	const apiKey = isPreview ? process.env.AGILITY_API_PREVIEW_KEY : process.env.AGILITY_API_FETCH_KEY
+
+	return agility.getApi({
+		guid: process.env.AGILITY_GUID,
+		apiKey,
+		isPreview
+	});
+}
+
+export default getAgilitySDK
+

package/templates/lib/cms/getContentItem.ts

@@ -0,0 +1,20 @@
+import { type ContentItemRequestParams } from "@agility/content-fetch/dist/methods/getContentItem"
+import getAgilitySDK from "@/lib/cms/getAgilitySDK"
+import { type ContentItem } from "@agility/content-fetch"
+
+/**
+ * Get a content item with caching information added.
+ */
+export const getContentItem = async <T>(params: ContentItemRequestParams) => {
+	const agilitySDK = await getAgilitySDK()
+
+	agilitySDK.config.fetchConfig = {
+		next: {
+			tags: [`agility-content-${params.contentID}-${params.languageCode || params.locale}`],
+			revalidate: 60,
+		},
+	}
+
+	return await agilitySDK.getContentItem(params) as ContentItem<T>
+}
+

package/templates/lib/cms/getContentList.ts

@@ -0,0 +1,19 @@
+import getAgilitySDK from "@/lib/cms/getAgilitySDK"
+import type { ContentListRequestParams } from "@agility/content-fetch/dist/methods/getContentList"
+
+/**
+ * Get a content list with caching information added.
+ */
+export const getContentList = async <T>(params: ContentListRequestParams) => {
+	const agilitySDK = await getAgilitySDK()
+
+	agilitySDK.config.fetchConfig = {
+		next: {
+			tags: [`agility-content-${params.referenceName.toLowerCase()}-${params.languageCode || params.locale}`],
+			revalidate: 60,
+		},
+	}
+
+	return await agilitySDK.getContentList(params)
+}
+

package/templates/lib/cms/getRedirections.ts

@@ -0,0 +1,85 @@
+import agility from '@agility/content-fetch'
+
+export interface Redirection {
+	id: number
+	originUrl: string
+	destinationUrl: string
+	statusCode: number
+}
+
+interface Redirections {
+	lastAccessDate: string
+	isUpToDate: boolean
+	items: Redirection[]
+}
+
+export interface RedirectionsMap {
+	lastAccessDate: string
+	isUpToDate: boolean
+	items: { [key: string]: Redirection }
+}
+
+interface Props {
+	forceUpdate?: boolean
+}
+
+/**
+ * Get the list of redirections from Agility CMS.
+ */
+export const getRedirections = async ({ forceUpdate = false }: Props): Promise<RedirectionsMap> => {
+	const apiKey = process.env.AGILITY_API_FETCH_KEY
+
+	const agilitySDK = agility.getApi({
+		guid: process.env.AGILITY_GUID,
+		apiKey,
+		isPreview: false
+	});
+
+	agilitySDK.config.fetchConfig = {
+		next: {
+			revalidate: 0,
+		},
+	}
+
+	try {
+		let lastAccessDate: Date | null | undefined = undefined
+		const redirectionsFromServer = await agilitySDK.getUrlRedirections({ lastAccessDate }) as Redirections
+
+		if (!redirectionsFromServer.isUpToDate || forceUpdate) {
+			const redirectionsMap: RedirectionsMap = {
+				lastAccessDate: redirectionsFromServer.lastAccessDate,
+				isUpToDate: redirectionsFromServer.isUpToDate,
+				items: {}
+			}
+
+			redirectionsFromServer.items.forEach((redirection) => {
+				let key = redirection.originUrl.toLowerCase()
+				if (key.startsWith("~/")) key = key.substring(1)
+				if (key.includes("://")) {
+					const hostIndex = key.indexOf("/", key.indexOf("://") + 3)
+					key = key.substring(hostIndex)
+				}
+				if (redirection.destinationUrl.startsWith("~/")) {
+					redirection.destinationUrl = redirection.destinationUrl.substring(1)
+				}
+				redirectionsMap.items[key] = redirection
+			});
+
+			return redirectionsMap
+		}
+
+		return {
+			lastAccessDate: redirectionsFromServer.lastAccessDate,
+			isUpToDate: redirectionsFromServer.isUpToDate,
+			items: {}
+		}
+	} catch (error) {
+		console.error('Failed to fetch redirections:', error);
+		return {
+			lastAccessDate: new Date().toISOString(),
+			isUpToDate: false,
+			items: {}
+		}
+	}
+}
+

package/templates/lib/cms/getSitemapFlat.ts

@@ -0,0 +1,19 @@
+import getAgilitySDK from "@/lib/cms/getAgilitySDK"
+import { type SitemapFlatRequestParams } from "@agility/content-fetch/dist/methods/getSitemapFlat"
+
+/**
+ * Get the flat sitemap for the given language code, with caching information added.
+ */
+export const getSitemapFlat = async (params: SitemapFlatRequestParams) => {
+	const agilitySDK = await getAgilitySDK()
+
+	agilitySDK.config.fetchConfig = {
+		next: {
+			tags: [`agility-sitemap-flat-${params.languageCode || params.locale}`],
+			revalidate: 60,
+		},
+	}
+
+	return await agilitySDK.getSitemapFlat(params)
+}
+

package/templates/lib/cms/getSitemapNested.ts

@@ -0,0 +1,19 @@
+import getAgilitySDK from "@/lib/cms/getAgilitySDK"
+import { type SitemapNestedRequestParams } from "@agility/content-fetch/dist/methods/getSitemapNested"
+
+/**
+ * Get the nested sitemap for the given language code, with caching information added.
+ */
+export const getSitemapNested = async (params: SitemapNestedRequestParams) => {
+	const agilitySDK = await getAgilitySDK()
+
+	agilitySDK.config.fetchConfig = {
+		next: {
+			tags: [`agility-sitemap-nested-${params.languageCode || params.locale}`],
+			revalidate: 60,
+		},
+	}
+
+	return await agilitySDK.getSitemapNested(params)
+}
+

package/templates/lib/env.ts

@@ -0,0 +1,99 @@
+/**
+ * Strongly typed environment variables utility
+ * Provides runtime validation and type safety for environment variables
+ */
+
+type RequiredEnvVars = {
+	// Agility CMS
+	AGILITY_GUID: string
+	AGILITY_API_FETCH_KEY: string
+	AGILITY_API_PREVIEW_KEY: string
+	AGILITY_SECURITY_KEY: string
+	AGILITY_LOCALES: string
+	AGILITY_SITEMAP: string
+	AGILITY_FETCH_CACHE_DURATION: string
+	AGILITY_PATH_REVALIDATE_DURATION: string
+
+	// Node.js
+	NODE_ENV: 'development' | 'production' | 'test'
+}
+
+type OptionalEnvVars = {
+	// Add any optional environment variables here
+}
+
+type EnvVars = RequiredEnvVars & Partial<OptionalEnvVars>
+
+/**
+ * Get a required environment variable with runtime validation
+ */
+function getRequiredEnvVar<K extends keyof RequiredEnvVars>(key: K): RequiredEnvVars[K] {
+	const value = process.env[key]
+
+	if (!value) {
+		throw new Error(`Missing required environment variable: ${key}`)
+	}
+
+	// Special validation for NODE_ENV
+	if (key === 'NODE_ENV' && !['development', 'production', 'test'].includes(value)) {
+		throw new Error(`Invalid NODE_ENV value: ${value}. Must be 'development', 'production', or 'test'`)
+	}
+
+	return value as RequiredEnvVars[K]
+}
+
+/**
+ * Get an optional environment variable
+ */
+function getOptionalEnvVar<K extends keyof OptionalEnvVars>(key: K, defaultValue?: OptionalEnvVars[K]): OptionalEnvVars[K] | undefined {
+	return process.env[key] as OptionalEnvVars[K] || defaultValue
+}
+
+/**
+ * Get all environment variables with validation
+ */
+function getAllEnvVars(): EnvVars {
+	return {
+		// Agility CMS
+		AGILITY_GUID: getRequiredEnvVar('AGILITY_GUID'),
+		AGILITY_API_FETCH_KEY: getRequiredEnvVar('AGILITY_API_FETCH_KEY'),
+		AGILITY_API_PREVIEW_KEY: getRequiredEnvVar('AGILITY_API_PREVIEW_KEY'),
+		AGILITY_SECURITY_KEY: getRequiredEnvVar('AGILITY_SECURITY_KEY'),
+		AGILITY_LOCALES: getRequiredEnvVar('AGILITY_LOCALES'),
+		AGILITY_SITEMAP: getRequiredEnvVar('AGILITY_SITEMAP'),
+		AGILITY_FETCH_CACHE_DURATION: getRequiredEnvVar('AGILITY_FETCH_CACHE_DURATION'),
+		AGILITY_PATH_REVALIDATE_DURATION: getRequiredEnvVar('AGILITY_PATH_REVALIDATE_DURATION'),
+
+		// Node.js
+		NODE_ENV: getRequiredEnvVar('NODE_ENV'),
+	}
+}
+
+/**
+ * Typed environment variables object
+ * Use this instead of process.env for type safety
+ */
+export const env = {
+	get: getRequiredEnvVar,
+	getOptional: getOptionalEnvVar,
+	getAll: getAllEnvVars,
+
+	// Direct access to commonly used variables
+	get AGILITY_GUID() { return getRequiredEnvVar('AGILITY_GUID') },
+	get AGILITY_API_FETCH_KEY() { return getRequiredEnvVar('AGILITY_API_FETCH_KEY') },
+	get AGILITY_API_PREVIEW_KEY() { return getRequiredEnvVar('AGILITY_API_PREVIEW_KEY') },
+	get AGILITY_SECURITY_KEY() { return getRequiredEnvVar('AGILITY_SECURITY_KEY') },
+	get AGILITY_LOCALES() { return getRequiredEnvVar('AGILITY_LOCALES') },
+	get AGILITY_SITEMAP() { return getRequiredEnvVar('AGILITY_SITEMAP') },
+	get AGILITY_FETCH_CACHE_DURATION() { return getRequiredEnvVar('AGILITY_FETCH_CACHE_DURATION') },
+	get AGILITY_PATH_REVALIDATE_DURATION() { return getRequiredEnvVar('AGILITY_PATH_REVALIDATE_DURATION') },
+	get NODE_ENV() { return getRequiredEnvVar('NODE_ENV') },
+
+	// Computed values
+	get isDevelopment() { return getRequiredEnvVar('NODE_ENV') === 'development' },
+	get isProduction() { return getRequiredEnvVar('NODE_ENV') === 'production' },
+	get isTest() { return getRequiredEnvVar('NODE_ENV') === 'test' },
+} as const
+
+export type { RequiredEnvVars, OptionalEnvVars, EnvVars }
+

package/templates/lib/i18n/config.ts

@@ -0,0 +1,28 @@
+// Get locales from environment variable, fallback to default
+const envLocales = process.env.AGILITY_LOCALES?.split(',') || ['en-us']
+export const locales = envLocales as readonly string[]
+export const defaultLocale = envLocales[0] || 'en-us'
+export type Locale = typeof locales[number]
+
+export function isValidLocale(locale: string, locales: readonly string[]): locale is Locale {
+  return locales.includes(locale as Locale)
+}
+
+export function getLocaleFromPathname(pathname: string, locales: readonly string[]): Locale | null {
+  const segments = pathname.split('/')
+  const potentialLocale = segments[1]
+
+  if (isValidLocale(potentialLocale, locales)) {
+    return potentialLocale
+  }
+
+  return null
+}
+
+export function removeLocaleFromPathname(pathname: string, locale: Locale): string {
+  if (pathname.startsWith(`/${locale}`)) {
+    return pathname.slice(`/${locale}`.length) || '/'
+  }
+  return pathname
+}
+

package/templates/proxy.ts

@@ -0,0 +1,101 @@
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+import { defaultLocale, locales, isValidLocale, getLocaleFromPathname, removeLocaleFromPathname } from './lib/i18n/config'
+
+export async function proxy(request: NextRequest) {
+	/*****************************
+	 * *** AGILITY PROXY ***
+	 * 1: Check if this is a preview request,
+	 * 2: Check if we are exiting preview
+	 * 3: Check if this is a direct to a dynamic page
+	 *    based on a content id
+	 *******************************/
+
+	let pathname = request.nextUrl.pathname
+	const previewQ = request.nextUrl.searchParams.get("AgilityPreview")
+	let contentIDStr = request.nextUrl.searchParams.get("ContentID") as string || ""
+
+	const ext = request.nextUrl.pathname.includes(".") ? request.nextUrl.pathname.split('.').pop() : null
+
+	if (request.nextUrl.searchParams.has("agilitypreviewkey")) {
+		//*** this is a preview request ***
+		const agilityPreviewKey = request.nextUrl.searchParams.get("agilitypreviewkey") || ""
+		const locale = request.nextUrl.searchParams.get("lang")
+		const slug = request.nextUrl.pathname
+		let redirectUrl = `${request.nextUrl.protocol}//${request.nextUrl.host}/api/preview?locale=${locale}&ContentID=${contentIDStr}&slug=${encodeURIComponent(slug)}&agilitypreviewkey=${encodeURIComponent(agilityPreviewKey)}`
+		return NextResponse.redirect(redirectUrl)
+	} else if (previewQ === "0") {
+		//*** exit preview
+		const locale = request.nextUrl.searchParams.get("lang")
+		const slug = request.nextUrl.pathname
+		let redirectUrl = `${request.nextUrl.protocol}//${request.nextUrl.host}/api/preview/exit?locale=${locale}&ContentID=${contentIDStr}&slug=${encodeURIComponent(slug)}`
+		return NextResponse.redirect(redirectUrl)
+	} else if (contentIDStr) {
+		const contentID = parseInt(contentIDStr)
+		if (!isNaN(contentID) && contentID > 0) {
+			//*** this is a dynamic page request ***
+			let dynredirectUrl = `${request.nextUrl.protocol}//${request.nextUrl.host}/api/dynamic-redirect?ContentID=${contentID}`
+			return NextResponse.rewrite(dynredirectUrl)
+		}
+	} else if ((!ext || ext.length === 0)) {
+		/**************************************
+		 * SPECIAL CASE FOR lang= QUERY PARAM *
+		 **************************************/
+		const langParam = request.nextUrl.searchParams.get("lang")
+		const currentLocale = getLocaleFromPathname(pathname, locales) || defaultLocale
+
+		if (langParam && isValidLocale(langParam, locales) && langParam !== currentLocale) {
+			if (langParam === defaultLocale) {
+				const redirectUrl = new URL(request.nextUrl.toString())
+				redirectUrl.pathname = removeLocaleFromPathname(pathname, currentLocale)
+				redirectUrl.searchParams.delete("lang")
+				return NextResponse.redirect(redirectUrl)
+			} else {
+				const redirectUrl = new URL(request.nextUrl.toString())
+				const pathnameWithoutLocale = removeLocaleFromPathname(pathname, currentLocale)
+				redirectUrl.pathname = `/${langParam}${pathnameWithoutLocale}`
+				redirectUrl.searchParams.delete("lang")
+				return NextResponse.redirect(redirectUrl)
+			}
+		}
+
+		/************************
+		 * HANDLE SEARCH PARAMS *
+		 ************************/
+		let searchParams = request.nextUrl.searchParams.toString()
+		let hasSearchParams = searchParams && searchParams.length > 0
+		if (!hasSearchParams) {
+			searchParams = ""
+		}
+
+		if (searchParams && searchParams.length > 0) {
+			const searchParamPortion = `~~~${encodeURIComponent(searchParams)}~~~`
+			pathname = pathname.endsWith("/") ? `${pathname}${searchParamPortion}` : `${pathname}/${searchParamPortion}`
+		}
+
+		/************************
+		 * LOCALE BASED ROUTING *
+		 ************************/
+		const hasLocalePrefix = locales.some(locale => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`)
+		const isStaticFile = pathname.includes('.') || pathname.startsWith('/_next')
+
+		const baseUrl = request.nextUrl.origin
+
+		if (!hasLocalePrefix && !isStaticFile) {
+			const localeBasedUrl = new URL(`/${defaultLocale}${pathname}`, baseUrl)
+			return NextResponse.rewrite(localeBasedUrl)
+		}
+
+		if (hasSearchParams) {
+			const searchParamUrl = new URL(pathname, baseUrl)
+			return NextResponse.rewrite(searchParamUrl)
+		}
+	}
+}
+
+export const config = {
+	matcher: [
+		'/((?!api|assets|_next/static|_next/image|favicon.ico).*)',
+	],
+}
+

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "templates"]
+}
+