@fedify/astro 2.1.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2024–2026 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+<!-- deno-fmt-ignore-file -->
+
+@fedify/astro: Integrate Fedify with `Astro`
+============================================
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+[![Follow @fedify@hollo.social][@fedify@hollo.social badge]][@fedify@hollo.social]
+
+*This package is available since Fedify 2.1.0.*
+
+This package provides a simple way to integrate [Fedify] with [Astro].
+
+First, add the integration to your *astro.config.mjs*:
+
+~~~~ typescript
+import { defineConfig } from "astro/config";
+import { fedifyIntegration } from "@fedify/astro";
+
+export default defineConfig({
+  integrations: [fedifyIntegration()],
+  output: "server",
+});
+~~~~
+
+Then, create your middleware in *src/middleware.ts*:
+
+~~~~ typescript
+import { createFederation } from "@fedify/fedify";
+import { fedifyMiddleware } from "@fedify/astro";
+
+const federation = createFederation<void>({
+  // Omitted for brevity; see the related section for details.
+});
+
+export const onRequest = fedifyMiddleware(
+  federation,
+  (context) => void 0,
+);
+~~~~
+
+[JSR badge]: https://jsr.io/badges/@fedify/astro
+[JSR]: https://jsr.io/@fedify/astro
+[npm badge]: https://img.shields.io/npm/v/@fedify/astro?logo=npm
+[npm]: https://www.npmjs.com/package/@fedify/astro
+[@fedify@hollo.social badge]: https://fedi-badge.deno.dev/@fedify@hollo.social/followers.svg
+[@fedify@hollo.social]: https://hollo.social/@fedify
+[Fedify]: https://fedify.dev/
+[Astro]: https://astro.build/
+
+
+For Deno users
+--------------
+
+If you are using Deno, you should import `@deno/vite-adapter` in
+*astro.config.mjs* and use it as the adapter:
+
+~~~~ typescript
+import { defineConfig } from "astro/config";
+import { fedifyIntegration } from "@fedify/astro";
+import deno from "@deno/vite-adapter";
+import deno from "@deno/astro-adapter";
+
+export default defineConfig({
+  integrations: [fedifyIntegration()],
+  output: "server",
+  adapter: deno(),
+});
+~~~~
+
+And the tasks in *deno.json* should be updated to use `deno run npm:astro`
+instead of `astro`:
+
+~~~~ json
+{
+  "tasks": {
+    "dev": "deno run -A npm:astro dev",
+    "build": "deno run -A npm:astro build",
+    "preview": "deno run -A npm:astro preview"
+  }
+}
+~~~~
+
+
+How it works
+------------
+
+Fedify behaves as a middleware that wraps around the Astro request handler.
+The middleware intercepts the incoming HTTP requests and dispatches them to
+the appropriate handler based on the request path and the `Accept` header
+(i.e., content negotiation).  This architecture allows Fedify and your Astro
+application to coexist in the same domain and port.
+
+The `fedifyIntegration()` function configures Vite's SSR settings to ensure
+that `@fedify/fedify` and `@fedify/vocab` are properly bundled during SSR.
+
+For example, if you make a request to */.well-known/webfinger* Fedify will
+handle the request by itself, but if you make a request to */users/alice*
+(assuming your Astro app has a page for that path) with
+`Accept: text/html` header, Fedify will dispatch the request to Astro's
+page handler.  Or if you define an actor dispatcher
+for `/users/{identifier}` in Fedify, and the request is made with
+`Accept: application/activity+json` header, Fedify will dispatch the request
+to the appropriate actor dispatcher.
+
+
+Installation
+------------
+
+~~~~ sh
+deno add jsr:@fedify/astro  # Deno
+npm  add     @fedify/astro  # npm
+pnpm add     @fedify/astro  # pnpm
+yarn add     @fedify/astro  # Yarn
+bun  add     @fedify/astro  # Bun
+~~~~

package/dist/mod.cjs

@@ -0,0 +1,89 @@
+
+//#region src/mod.ts
+/**
+* Create an Astro integration that configures Vite SSR settings for
+* Fedify compatibility.
+*
+* This integration adds `@fedify/fedify` and `@fedify/vocab` to Vite's
+* `ssr.noExternal` list, which is necessary because these packages contain
+* dependencies that Vite must bundle for SSR.
+*
+* @example astro.config.mjs
+* ``` typescript
+* import { defineConfig } from "astro/config";
+* import { fedifyIntegration } from "@fedify/astro";
+*
+* export default defineConfig({
+*   integrations: [fedifyIntegration()],
+*   output: "server",
+* });
+* ```
+*
+* @returns An Astro integration object.
+* @since 2.1.0
+*/
+function fedifyIntegration() {
+	return {
+		name: "@fedify/astro",
+		hooks: { "astro:config:setup": ({ updateConfig }) => {
+			updateConfig({ vite: { ssr: { noExternal: ["@fedify/fedify", "@fedify/vocab"] } } });
+		} }
+	};
+}
+/**
+* Create an Astro middleware to integrate with the {@link Federation} object.
+*
+* @example src/middleware.ts
+* ``` typescript
+* import { createFederation } from "@fedify/fedify";
+* import { fedifyMiddleware } from "@fedify/astro";
+*
+* const federation = createFederation<void>({
+*   // Omitted for brevity; see the related section for details.
+* });
+*
+* export const onRequest = fedifyMiddleware(
+*   federation,
+*   (context) => undefined,
+* );
+* ```
+*
+* @template TContextData A type of the context data for the
+*                        {@link Federation} object.
+* @param federation A {@link Federation} object to integrate with Astro.
+* @param contextDataFactory A function to create a context data for the
+*                           {@link Federation} object.
+* @returns An Astro middleware function.
+* @since 2.1.0
+*/
+function fedifyMiddleware(federation, contextDataFactory) {
+	return async (context, next) => {
+		const contextData = await contextDataFactory(context);
+		return await federation.fetch(context.request, {
+			contextData,
+			...integrateFetchOptions(next)
+		});
+	};
+}
+function integrateFetchOptions(next) {
+	return {
+		async onNotFound(_request) {
+			return await next();
+		},
+		async onNotAcceptable(_request) {
+			const response = await next();
+			if (response.status !== 404) return response;
+			return new Response("Not acceptable", {
+				status: 406,
+				headers: {
+					"Content-Type": "text/plain",
+					Vary: "Accept"
+				}
+			});
+		}
+	};
+}
+
+//#endregion
+exports.fedifyIntegration = fedifyIntegration;
+exports.fedifyMiddleware = fedifyMiddleware;

package/dist/mod.d.cts

@@ -0,0 +1,68 @@
+import { Federation } from "@fedify/fedify/federation";
+import { APIContext, AstroIntegration, MiddlewareHandler } from "astro";
+
+//#region src/mod.d.ts
+
+/**
+ * A factory function to create a context data for the {@link Federation}
+ * object.
+ *
+ * @template TContextData A type of the context data for the
+ *                        {@link Federation} object.
+ * @param context An Astro context object.
+ * @returns A context data for the {@link Federation} object.
+ * @since 2.1.0
+ */
+type ContextDataFactory<TContextData> = (context: APIContext) => TContextData | Promise<TContextData>;
+/**
+ * Create an Astro integration that configures Vite SSR settings for
+ * Fedify compatibility.
+ *
+ * This integration adds `@fedify/fedify` and `@fedify/vocab` to Vite's
+ * `ssr.noExternal` list, which is necessary because these packages contain
+ * dependencies that Vite must bundle for SSR.
+ *
+ * @example astro.config.mjs
+ * ``` typescript
+ * import { defineConfig } from "astro/config";
+ * import { fedifyIntegration } from "@fedify/astro";
+ *
+ * export default defineConfig({
+ *   integrations: [fedifyIntegration()],
+ *   output: "server",
+ * });
+ * ```
+ *
+ * @returns An Astro integration object.
+ * @since 2.1.0
+ */
+declare function fedifyIntegration(): AstroIntegration;
+/**
+ * Create an Astro middleware to integrate with the {@link Federation} object.
+ *
+ * @example src/middleware.ts
+ * ``` typescript
+ * import { createFederation } from "@fedify/fedify";
+ * import { fedifyMiddleware } from "@fedify/astro";
+ *
+ * const federation = createFederation<void>({
+ *   // Omitted for brevity; see the related section for details.
+ * });
+ *
+ * export const onRequest = fedifyMiddleware(
+ *   federation,
+ *   (context) => undefined,
+ * );
+ * ```
+ *
+ * @template TContextData A type of the context data for the
+ *                        {@link Federation} object.
+ * @param federation A {@link Federation} object to integrate with Astro.
+ * @param contextDataFactory A function to create a context data for the
+ *                           {@link Federation} object.
+ * @returns An Astro middleware function.
+ * @since 2.1.0
+ */
+declare function fedifyMiddleware<TContextData>(federation: Federation<TContextData>, contextDataFactory: ContextDataFactory<TContextData>): MiddlewareHandler;
+//#endregion
+export { ContextDataFactory, fedifyIntegration, fedifyMiddleware };

package/dist/mod.d.ts

@@ -0,0 +1,68 @@
+import { Federation } from "@fedify/fedify/federation";
+import { APIContext, AstroIntegration, MiddlewareHandler } from "astro";
+
+//#region src/mod.d.ts
+
+/**
+ * A factory function to create a context data for the {@link Federation}
+ * object.
+ *
+ * @template TContextData A type of the context data for the
+ *                        {@link Federation} object.
+ * @param context An Astro context object.
+ * @returns A context data for the {@link Federation} object.
+ * @since 2.1.0
+ */
+type ContextDataFactory<TContextData> = (context: APIContext) => TContextData | Promise<TContextData>;
+/**
+ * Create an Astro integration that configures Vite SSR settings for
+ * Fedify compatibility.
+ *
+ * This integration adds `@fedify/fedify` and `@fedify/vocab` to Vite's
+ * `ssr.noExternal` list, which is necessary because these packages contain
+ * dependencies that Vite must bundle for SSR.
+ *
+ * @example astro.config.mjs
+ * ``` typescript
+ * import { defineConfig } from "astro/config";
+ * import { fedifyIntegration } from "@fedify/astro";
+ *
+ * export default defineConfig({
+ *   integrations: [fedifyIntegration()],
+ *   output: "server",
+ * });
+ * ```
+ *
+ * @returns An Astro integration object.
+ * @since 2.1.0
+ */
+declare function fedifyIntegration(): AstroIntegration;
+/**
+ * Create an Astro middleware to integrate with the {@link Federation} object.
+ *
+ * @example src/middleware.ts
+ * ``` typescript
+ * import { createFederation } from "@fedify/fedify";
+ * import { fedifyMiddleware } from "@fedify/astro";
+ *
+ * const federation = createFederation<void>({
+ *   // Omitted for brevity; see the related section for details.
+ * });
+ *
+ * export const onRequest = fedifyMiddleware(
+ *   federation,
+ *   (context) => undefined,
+ * );
+ * ```
+ *
+ * @template TContextData A type of the context data for the
+ *                        {@link Federation} object.
+ * @param federation A {@link Federation} object to integrate with Astro.
+ * @param contextDataFactory A function to create a context data for the
+ *                           {@link Federation} object.
+ * @returns An Astro middleware function.
+ * @since 2.1.0
+ */
+declare function fedifyMiddleware<TContextData>(federation: Federation<TContextData>, contextDataFactory: ContextDataFactory<TContextData>): MiddlewareHandler;
+//#endregion
+export { ContextDataFactory, fedifyIntegration, fedifyMiddleware };

package/dist/mod.js

@@ -0,0 +1,87 @@
+//#region src/mod.ts
+/**
+* Create an Astro integration that configures Vite SSR settings for
+* Fedify compatibility.
+*
+* This integration adds `@fedify/fedify` and `@fedify/vocab` to Vite's
+* `ssr.noExternal` list, which is necessary because these packages contain
+* dependencies that Vite must bundle for SSR.
+*
+* @example astro.config.mjs
+* ``` typescript
+* import { defineConfig } from "astro/config";
+* import { fedifyIntegration } from "@fedify/astro";
+*
+* export default defineConfig({
+*   integrations: [fedifyIntegration()],
+*   output: "server",
+* });
+* ```
+*
+* @returns An Astro integration object.
+* @since 2.1.0
+*/
+function fedifyIntegration() {
+	return {
+		name: "@fedify/astro",
+		hooks: { "astro:config:setup": ({ updateConfig }) => {
+			updateConfig({ vite: { ssr: { noExternal: ["@fedify/fedify", "@fedify/vocab"] } } });
+		} }
+	};
+}
+/**
+* Create an Astro middleware to integrate with the {@link Federation} object.
+*
+* @example src/middleware.ts
+* ``` typescript
+* import { createFederation } from "@fedify/fedify";
+* import { fedifyMiddleware } from "@fedify/astro";
+*
+* const federation = createFederation<void>({
+*   // Omitted for brevity; see the related section for details.
+* });
+*
+* export const onRequest = fedifyMiddleware(
+*   federation,
+*   (context) => undefined,
+* );
+* ```
+*
+* @template TContextData A type of the context data for the
+*                        {@link Federation} object.
+* @param federation A {@link Federation} object to integrate with Astro.
+* @param contextDataFactory A function to create a context data for the
+*                           {@link Federation} object.
+* @returns An Astro middleware function.
+* @since 2.1.0
+*/
+function fedifyMiddleware(federation, contextDataFactory) {
+	return async (context, next) => {
+		const contextData = await contextDataFactory(context);
+		return await federation.fetch(context.request, {
+			contextData,
+			...integrateFetchOptions(next)
+		});
+	};
+}
+function integrateFetchOptions(next) {
+	return {
+		async onNotFound(_request) {
+			return await next();
+		},
+		async onNotAcceptable(_request) {
+			const response = await next();
+			if (response.status !== 404) return response;
+			return new Response("Not acceptable", {
+				status: 406,
+				headers: {
+					"Content-Type": "text/plain",
+					Vary: "Accept"
+				}
+			});
+		}
+	};
+}
+
+//#endregion
+export { fedifyIntegration, fedifyMiddleware };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@fedify/astro",
+  "version": "2.1.0-dev.0",
+  "description": "Integrate Fedify with Astro",
+  "keywords": [
+    "Fedify",
+    "ActivityPub",
+    "Fediverse",
+    "Astro"
+  ],
+  "author": {
+    "name": "ChanHaeng Lee",
+    "email": "2chanhaeng@gmail.com",
+    "url": "https://chomu.dev/"
+  },
+  "homepage": "https://fedify.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fedify-dev/fedify.git",
+    "directory": "packages/astro"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/fedify-dev/fedify/issues"
+  },
+  "funding": [
+    "https://opencollective.com/fedify",
+    "https://github.com/sponsors/dahlia"
+  ],
+  "type": "module",
+  "main": "./dist/mod.cjs",
+  "module": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/mod.d.cts",
+        "default": "./dist/mod.cjs"
+      },
+      "import": {
+        "types": "./dist/mod.d.ts",
+        "default": "./dist/mod.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "package.json"
+  ],
+  "peerDependencies": {
+    "astro": "^5.0.0",
+    "@fedify/fedify": "^2.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.12.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build:self": "tsdown",
+    "build": "pnpm --filter @fedify/astro... run build:self",
+    "prepublish": "pnpm build",
+    "test": "node --experimental-transform-types --test"
+  }
+}