@easy-web/swa 1.0.0

package/README.md

@@ -0,0 +1,73 @@
+# @easy-web/swa
+
+Astro integration that manages Azure Static Web Apps (SWA) 404 handling via a sentinel-marked sidecar file. Ensures the integration's configuration changes are preserved across rebuilds while respecting user-authored settings.
+
+## What it does
+
+When you add `easyWebNotFound()` to your Astro config, the integration:
+
+1. **Reads** the existing `staticwebapp.config.json` at build time (if present)
+2. **Emits** a global 404 response override (`responseOverrides.404`) that rewrites unmatched routes to `/404.html`
+3. **Tracks ownership** via a sidecar file (`staticwebapp.config.json.easy-web-managed.json`) so future builds know which settings the integration manages
+4. **Preserves** all user-authored settings: `auth`, `globalHeaders`, `navigationFallback`, custom routes, and any other `responseOverrides` the user defined
+
+## Usage
+
+```ts
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import easyWebNotFound from '@easy-web/swa';
+
+export default defineConfig({
+  integrations: [
+    easyWebNotFound(),
+  ],
+});
+```
+
+The integration requires no configuration. The `Options` type (with optional `defaultLocale` and `locales` fields) is retained for API compatibility but has no effect in v0.2.0+.
+
+## How it works
+
+### The sidecar file
+
+SWA's `staticwebapp.config.json` schema uses `additionalProperties: false` at the root, which means the config file cannot store metadata about which keys are managed by which tool. To solve this, the integration maintains a sibling file:
+
+```json
+// staticwebapp.config.json.easy-web-managed.json
+{
+  "keys": ["responseOverrides.404"],
+  "version": "0.2.0",
+  "docs": "https://github.com/achimismaili/websites/blob/main/docs/decisions/0013-shared-not-found-primitives.md"
+}
+```
+
+On the next build, the integration reads this sidecar to determine which keys it previously claimed. If the sidecar says it owns `responseOverrides.404`, the integration updates it; otherwise, it leaves the user's 404 override untouched.
+
+### Single global 404 limitation
+
+Azure Static Web Apps supports only **one global 404 response override**. This integration emits a single, locale-agnostic 404 handler. If your site uses i18n:
+
+- Unmatched routes in any locale will serve the **default-locale 404 body** (from `/404.html`)
+- Per-locale 404 content is **not supported** by this integration
+- If you need locale-specific 404 pages, you must implement them outside this integration (e.g., via Astro routing or a custom SWA configuration)
+
+See [ADR 0013 — Shared Not-Found Primitives](https://github.com/achimismaili/websites/blob/main/docs/decisions/0013-shared-not-found-primitives.md) for the full rationale.
+
+## Preservation guarantees
+
+The integration **only manages** `responseOverrides.404`. All other settings are preserved exactly as you authored them:
+
+- ✅ `auth` — untouched
+- ✅ `globalHeaders` — untouched
+- ✅ `navigationFallback` — untouched
+- ✅ `routes` — untouched
+- ✅ Other `responseOverrides` — untouched
+- ✅ All other root keys — untouched
+
+If you define your own `responseOverrides.404` before the integration runs, the integration will detect this and skip managing the 404 override, logging a warning instead.
+
+## Compatibility
+
+- **Astro:** `>=6.0.0 <8.0.0`
+- **Node.js:** `>=18.0.0`

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import type { AstroIntegration } from 'astro';
+/**
+ * Options retained for compatibility with the 0.1.x API.
+ *
+ * Azure Static Web Apps supports one global 404 response override, so locale
+ * settings no longer affect the emitted configuration.
+ */
+export type Options = {
+    readonly defaultLocale?: string;
+    readonly locales?: readonly string[];
+};
+/**
+ * Astro integration that adds shared Azure Static Web Apps 404 handling.
+ *
+ * The main config contains only schema-legal keys. Ownership metadata lives in
+ * a sibling sidecar, and the integration updates `responseOverrides.404` only
+ * when that sidecar says the key is managed. User routes and every other SWA
+ * setting are preserved; no locale-wide rewrite routes are emitted.
+ */
+export declare function easyWebNotFound(_options?: Options): AstroIntegration;
+export default easyWebNotFound;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAK9C;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC;AAkCF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,GAAE,OAAY,GAAG,gBAAgB,CAkCxE;AAED,eAAe,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,152 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const SENTINEL_VERSION = '0.2.0';
+const SENTINEL_DOCS = 'https://github.com/achimismaili/websites/blob/main/docs/decisions/0013-shared-not-found-primitives.md';
+const KEY_RESPONSE_OVERRIDES_404 = 'responseOverrides.404';
+const SIDECAR_SUFFIX = '.easy-web-managed.json';
+const SCHEMA_LEGAL_ROOT_KEYS = new Set([
+    '$schema',
+    'routes',
+    'navigationFallback',
+    'responseOverrides',
+    'mimeTypes',
+    'globalHeaders',
+    'auth',
+    'networking',
+    'forwardingGateway',
+    'platform',
+    'trailingSlash',
+]);
+const MANAGED_RESPONSE_OVERRIDE = {
+    rewrite: '/404.html',
+    statusCode: 404,
+};
+/**
+ * Astro integration that adds shared Azure Static Web Apps 404 handling.
+ *
+ * The main config contains only schema-legal keys. Ownership metadata lives in
+ * a sibling sidecar, and the integration updates `responseOverrides.404` only
+ * when that sidecar says the key is managed. User routes and every other SWA
+ * setting are preserved; no locale-wide rewrite routes are emitted.
+ */
+export function easyWebNotFound(_options = {}) {
+    return {
+        name: '@easy-web/swa',
+        hooks: {
+            'astro:config:setup': ({ config }) => {
+                if (!config.i18n) {
+                    console.info('[easy-web-swa] no i18n config found — single-locale mode, emitting the global 404 override');
+                }
+                if (config.output === 'server') {
+                    console.warn('[easy-web-swa] non-static output detected; integration will write staticwebapp.config.json directly to dist/ instead of relying on public/ passthrough');
+                }
+            },
+            'astro:build:done': ({ dir }) => {
+                const distDir = fileURLToPath(dir);
+                const configPath = path.join(distDir, 'staticwebapp.config.json');
+                const sidecarPath = `${configPath}${SIDECAR_SUFFIX}`;
+                const existing = readConfig(configPath);
+                const previousSentinel = readSidecar(sidecarPath);
+                const { config, sentinel } = mergeConfig(existing, previousSentinel, configPath);
+                writeJson(configPath, config);
+                writeJson(sidecarPath, sentinel);
+            },
+        },
+    };
+}
+export default easyWebNotFound;
+function readConfig(configPath) {
+    if (!fs.existsSync(configPath))
+        return null;
+    return parseObjectFile(configPath);
+}
+function readSidecar(sidecarPath) {
+    if (!fs.existsSync(sidecarPath))
+        return null;
+    const value = parseObjectFile(sidecarPath);
+    const keys = value['keys'];
+    const version = value['version'];
+    const docs = value['docs'];
+    if (!Array.isArray(keys) ||
+        !keys.every((key) => typeof key === 'string') ||
+        typeof version !== 'string' ||
+        typeof docs !== 'string') {
+        throw new TypeError(`[easy-web-swa] invalid managed metadata in ${sidecarPath}`);
+    }
+    return { keys, version, docs };
+}
+function parseObjectFile(filePath) {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new SyntaxError(`[easy-web-swa] failed to parse JSON in ${filePath}: ${error.message}`);
+        }
+        throw error;
+    }
+    if (!isJsonObject(value)) {
+        throw new TypeError(`[easy-web-swa] expected a JSON object in ${filePath}`);
+    }
+    return value;
+}
+function mergeConfig(existing, previousSentinel, configPath) {
+    const config = schemaLegalConfig(existing);
+    const responseOverrides = readResponseOverrides(config, configPath);
+    const integrationOwns404 = previousSentinel?.keys.includes(KEY_RESPONSE_OVERRIDES_404) ?? false;
+    const userOwns404 = '404' in responseOverrides && !integrationOwns404;
+    if (userOwns404) {
+        console.warn('[easy-web-swa] user has defined responseOverrides.404; user override wins; integration will not manage it');
+        return { config, sentinel: makeSentinel([]) };
+    }
+    return {
+        config: {
+            ...config,
+            responseOverrides: {
+                ...responseOverrides,
+                '404': MANAGED_RESPONSE_OVERRIDE,
+            },
+        },
+        sentinel: makeSentinel([KEY_RESPONSE_OVERRIDES_404]),
+    };
+}
+function schemaLegalConfig(existing) {
+    if (existing === null)
+        return {};
+    const config = {};
+    for (const [key, value] of Object.entries(existing)) {
+        if (SCHEMA_LEGAL_ROOT_KEYS.has(key)) {
+            config[key] = value;
+        }
+        else {
+            console.warn(`[easy-web-swa] omitting non-schema-legal root key "${key}" from staticwebapp.config.json`);
+        }
+    }
+    return config;
+}
+function readResponseOverrides(config, configPath) {
+    const value = config['responseOverrides'];
+    if (value === undefined)
+        return {};
+    if (!isJsonObject(value)) {
+        throw new TypeError(`[easy-web-swa] expected responseOverrides to be an object in ${configPath}`);
+    }
+    return value;
+}
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function makeSentinel(keys) {
+    return {
+        keys,
+        version: SENTINEL_VERSION,
+        docs: SENTINEL_DOCS,
+    };
+}
+function writeJson(filePath, value) {
+    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@easy-web/swa",
+  "version": "1.0.0",
+  "type": "module",
+  "packageManager": "pnpm@10.34.4",
+  "description": "AstroIntegration that merges a sentinel-marked staticwebapp.config.json slice for shared 404 handling on Azure Static Web Apps.",
+  "keywords": [
+    "astro-integration",
+    "azure-static-web-apps",
+    "swa",
+    "staticwebapp",
+    "404",
+    "not-found"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "astro": ">=6.0.0 <8.0.0"
+  },
+  "devDependencies": {
+    "astro": "^6.4.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/achimismaili/easy-web.git",
+    "directory": "packages/easy-web-swa"
+  },
+  "license": "MIT"
+}