feat: built-in endpoint handler

README.md

@@ -9,9 +9,10 @@ A simple GraphQL server for Deno Fresh.
 
 ## Why `fresh-graphql`?
 
-1. Familiar developer experience with `fresh` projects.
-1. `deno deploy` has no dynamic imports.
-1. [`tRPC`](https://trpc.io) doesn't support deno (yet).
+1. You want file based routing.
+1. You want GraphQL.
+1. You have a [Deno Fresh](https://fresh.deno.dev) project.
+1. `deno deploy` does not support dynamic imports.
 
 ## Installation
 
@@ -54,36 +55,27 @@ await dev(import.meta.url, "./main.ts");
 
 ## Usage
 
+1. Run `deno task start`
+1. Visit `http://localhost:3000/graphql` for an GraphiQL interface.
+
 ### Entrypoint
 
-Any data handler routes would work, the example below uses the pathname
-`/graphql` as a convension.
+Our CLI will generate a default GraphQL endpoint for you, you may also do it
+manually by copying the contents below:
 
 ```ts
 // routes/graphql.ts
 
-import { type FreshContext } from "$fresh/server.ts";
-import { fromManifest } from "@vicary/fresh-graphql";
-import { createYoga } from "graphql-yoga";
+import { createHandler } from "@vicary/fresh-graphql";
 import manifest from "../graphql.gen.ts";
 
-// FRSH_GQL_DEV is set when you start the GraphQL development server in dev.ts.
-const debug = Deno.env.has("FRSH_GQL_DEV");
-
-const yoga = createYoga<FreshContext>({
-  graphiql: debug,
-  logging: debug,
-  maskedErrors: !debug,
-  schema: fromManifest(manifest),
-});
-
-export const handler = async (req: Request, ctx: FreshContext) => {
-  return await yoga.handleRequest(req, ctx);
-};
+export const handler = createHandler(manifest);
 ```
 
 ### Queries and Mutations
 
+This is a GraphQL version of the joke API when you create a new Fresh project.
+
 ```ts
 // graphql/Query/joke.ts
 

cli.ts

@@ -61,6 +61,14 @@ async function main() {
       log.error("Unable to patch deno.json, please try to do it manually.");
     }
   }
+
+  if (promptYesNo("Create default GraphQL endpoint at routes/graphql?", true)) {
+    if (!await createEndpoint("routes/graphql.ts")) {
+      log.error(
+        "Unable to create routes/graphql.ts, please try to do it manually.",
+      );
+    }
+  }
 }
 
 await main();
@@ -202,3 +210,21 @@ async function patchDenoJson(): Promise<boolean> {
 
   return true;
 }
+
+async function createEndpoint(path: string) {
+  try {
+    await Deno.writeTextFile(
+      path,
+      `// ${path}: GraphQL endpoint for fresh-graphql
+import { createHandler } from "@vicary/fresh-graphql";
+import manifest from "../graphql.gen.ts";
+
+export const handler = createHandler(manifest);
+`,
+    );
+  } catch {
+    return false;
+  }
+
+  return true;
+}

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@vicary/fresh-graphql",
-  "version": "0.2.9",
+  "version": "0.2.10-alpha.0",
   "exports": "./mod.ts",
   "publish": {
     "exclude": [

deps.ts

@@ -1,3 +1,4 @@
+export type { FreshContext } from "https://deno.land/x/[email protected]/server.ts";
 export { assert } from "jsr:@std/assert@^0.219.1/assert";
 export * as colors from "jsr:@std/fmt@^0.219.1/colors";
 export { ensureDir } from "jsr:@std/fs@^0.219.1/ensure_dir";
@@ -32,6 +33,7 @@ export {
   type SchemaMapper,
   type UnionTypeMapper,
 } from "npm:@graphql-tools/utils@^10.1.0";
+export { createYoga } from "npm:graphql-yoga@^5.3.0";
 export {
   defaultFieldResolver,
   type DirectiveDefinitionNode,

examples/graphql-yoga/routes/graphql.ts

@@ -1,18 +1,4 @@
-import { type FreshContext } from "$fresh/server.ts";
-import { fromManifest } from "@vicary/fresh-graphql";
-import { createYoga } from "graphql-yoga";
+import { createHandler } from "@vicary/fresh-graphql";
 import manifest from "../graphql.gen.ts";
 
-// FRSH_GQL_DEV is set when you start the GraphQL development server in dev.ts.
-const debug = Deno.env.has("FRSH_GQL_DEV");
-
-const yoga = createYoga<FreshContext>({
-  graphiql: debug,
-  logging: debug,
-  maskedErrors: !debug,
-  schema: fromManifest(manifest),
-});
-
-export const handler = async (req: Request, ctx: FreshContext) => {
-  return await yoga.handleRequest(req, ctx);
-};
+export const handler = createHandler(manifest);

mod.ts

@@ -5,6 +5,7 @@ export {
   type GraphQLTypeModule,
   type Manifest,
 } from "./schema.ts";
+export { createHandler } from "./server.ts";
 
 // Start interactive shell that automatically patches the fresh project.
 if (import.meta.main) {

schema.ts

@@ -18,7 +18,7 @@ import {
   type InterfaceTypeMapper,
   type IResolvers,
   makeExecutableSchema,
-  MapperKind,
+  type MapperKind,
   mapSchema,
   type ObjectTypeMapper,
   type ScalarTypeMapper,

server.ts

@@ -0,0 +1,26 @@
+import { createYoga, type FreshContext } from "./deps.ts";
+import type { Manifest } from "./schema.ts";
+import { fromManifest } from "./schema.ts";
+
+export type CreateHandlerOptions = {
+  debug?: boolean;
+};
+
+export function createHandler<TManifest extends Manifest>(
+  manifest: TManifest,
+  options?: CreateHandlerOptions,
+) {
+  // FRSH_GQL_DEV is set when you start the GraphQL development server in dev.ts.
+  const debug = options?.debug ?? Deno.env.has("FRSH_GQL_DEV");
+
+  const yoga = createYoga<FreshContext>({
+    graphiql: debug,
+    logging: debug,
+    maskedErrors: !debug,
+    schema: fromManifest(manifest),
+  });
+
+  return async (req: Request, ctx: FreshContext) => {
+    return await yoga.handleRequest(req, ctx);
+  };
+}