feat: throw error if /api routes defined (#142)

Author: geoffrich

README.md

@@ -172,6 +172,25 @@ export default {
 };
 ```
 
+### allowReservedSwaRoutes
+
+In production, Azure SWA will route any requests to `/api` or `/api/*` to the SWA [API backend](https://learn.microsoft.com/en-us/azure/static-web-apps/apis-overview). If you also define SvelteKit routes beginning with `/api`, those requests will work in dev, but return a 404 in production since the request will be routed to the SWA API. Because of this, the adapter will throw an error at build time if it detects any routes beginning with `/api`.
+
+If you want to disable this check, you can set `allowReservedSwaRoutes` to true. However, this will not start routing `/api` requests to your SvelteKit app. SWA does not allow configuring the `/api` route.
+
+```js
+import azure from 'svelte-adapter-azure-swa';
+
+export default {
+	kit: {
+		...
+		adapter: azure({
+			allowReservedSwaRoutes: true
+		})
+	}
+};
+```
+
 ### esbuildOptions
 
 An object containing additional [esbuild options](https://esbuild.github.io/api/#build-api). Currently only supports [external](https://esbuild.github.io/api/#external). If you require additional options to be exposed, plese [open an issue](https://github.com/geoffrich/svelte-adapter-azure-swa/issues).

index.d.ts

@@ -11,6 +11,7 @@ export type Options = {
 	esbuildOptions?: Pick<esbuild.BuildOptions, 'external'>;
 	apiDir?: string;
 	staticDir?: string;
+	allowReservedSwaRoutes?: boolean;
 };
 
 export default function plugin(options?: Options): Adapter;

index.js

@@ -49,7 +49,8 @@ export default function ({
 	customStaticWebAppConfig = {},
 	esbuildOptions = {},
 	apiDir: customApiDir = undefined,
-	staticDir: customStaticDir = undefined
+	staticDir: customStaticDir = undefined,
+	allowReservedSwaRoutes = false
 } = {}) {
 	return {
 		name: 'adapter-azure-swa',
@@ -62,6 +63,24 @@ export default function ({
 Please see the PR for migration instructions: https://github.com/geoffrich/svelte-adapter-azure-swa/pull/92`
 				);
 			}
+
+			const conflictingRoutes =
+				builder.routes?.map((route) => route.id).filter((routeId) => routeId.startsWith('/api')) ??
+				[];
+			if (!allowReservedSwaRoutes && conflictingRoutes.length > 0) {
+				builder.log.error(
+					`Error: the following routes conflict with Azure SWA's reserved /api route: ${conflictingRoutes.join(
+						', '
+					)}. Requests to these routes in production will return 404 instead of hitting your SvelteKit app.
+
+To resolve this error, move the conflicting routes so they do not start with /api. For example, move /api/blog to /blog.
+If you want to suppress this error, set allowReservedSwaRoutes to true in your adapter options.
+					`
+				);
+
+				throw new Error('Conflicting routes detected. Please rename the routes listed above.');
+			}
+
 			const swaConfig = generateConfig(customStaticWebAppConfig, builder.config.kit.appDir);
 
 			const tmp = builder.getBuildDirectory('azure-tmp');

test/index.test.js

@@ -123,6 +123,34 @@ describe('adapt', () => {
 			)
 		);
 	});
+
+	test.each(['/api', '/api/foo'])('throws error when the app defines %s route', async (routeId) => {
+		const adapter = azureAdapter();
+		const builder = getMockBuilder();
+		builder.routes.push({
+			id: routeId
+		});
+		await expect(adapter.adapt(builder)).rejects.toThrowError(
+			'Conflicting routes detected. Please rename the routes listed above.'
+		);
+	});
+
+	test('does not throw error for /api route if allowReservedSwaRoutes is defined', async () => {
+		const adapter = azureAdapter({ allowReservedSwaRoutes: true });
+		const builder = getMockBuilder();
+		builder.routes.push({
+			id: '/api'
+		});
+		await expect(adapter.adapt(builder)).resolves.not.toThrow();
+	});
+
+	test('handles null routes', async () => {
+		// builder.routes was added in 1.5 with route-level config
+		const adapter = azureAdapter();
+		const builder = getMockBuilder();
+		builder.routes = null;
+		await expect(adapter.adapt(builder)).resolves.not.toThrow();
+	});
 });
 
 /** @returns {import('@sveltejs/kit').Builder} */
@@ -135,7 +163,8 @@ function getMockBuilder() {
 		},
 		log: {
 			minor: vi.fn(),
-			warn: vi.fn()
+			warn: vi.fn(),
+			error: vi.fn()
 		},
 		prerendered: {
 			paths: ['/']
@@ -146,6 +175,14 @@ function getMockBuilder() {
 		getServerDirectory: vi.fn(() => 'server'),
 		rimraf: vi.fn(),
 		writeClient: vi.fn(),
-		writePrerendered: vi.fn()
+		writePrerendered: vi.fn(),
+		routes: [
+			{
+				id: '/'
+			},
+			{
+				id: '/about'
+			}
+		]
 	};
 }