eddev 2.3.12 → 2.3.14

package/skills/eddev/docs/routing/custom.mdx

@@ -0,0 +1,123 @@
+# Custom Routes (/docs/routing/custom)
+
+**Register fixed WordPress-backed routes for app-like screens.**
+
+In cases where we need a custom route, which does not necessarily map to a content type, you can use the `ED()->addCustomRoute()` function.
+
+This is mostly useful for sites which include app-like functionality — like login or checkout screens — where the URL should be fixed, and it shouldn't be removable by a client. It can also be useful for providing URLs to content which isn't a WordPress post or page, or for advanced customisation of routing.
+
+The `ED()->addCustomRoute()` function takes two arguments:
+
+1. The route pattern (a string), which is a simple PHP regular expression. Parenthesised groups can be extracted using dollar sign formatting.
+2. Options for the custom route:
+   * `template` (string, required) — pointing to the `.tsx` template file to be used, starting with `views/`
+   * `queryVars` (array, optional) — allows you to map a URL segment to a GraphQL parameter.
+   * `extraVars` (function) — accepts a PHP function which takes the `queryVars` from the previous step, and can return additional GraphQL parameters. This can be useful if you need to search the database for an ID.
+   * `title` (string or function, required) — the page title to use when viewing this route. If you pass a function, you can use the first parameter to read the query var values — allowing you to look up a title if necessary.
+   * `is404` (function, optional) - An optional callback function, which will be passed the query parameters, and should return a truthy value if the page should be a 404.
+
+Example:
+
+```php filename="/backend/routes.php"
+<?php
+
+// Adding a simple '/search' route, with an optional trailing slash.
+ED()->addCustomRoute("search/?$", [
+  'template' => 'views/search.tsx',
+  'title' => function() {
+    return 'Search';
+  }
+]);
+
+// Adding a custom route which uses a Regex pattern
+// The pattern is made available to a paired GraphQL file via a 'listId' variable.
+ED()->addCustomRoute("wishlist/([A-Za-z0-9\-\_]+)/?$", [
+  'template' => 'views/user-wishlist.tsx',
+  'queryVars' => [
+    'listId' => '$1'
+  ],
+  'title' => function($params) {
+    $wishlist = Wishlists::getWishlist($params['listId']);
+    return $wishlist->title;
+  },
+  'is404' => function($params) {
+    return Wishlists::wishlistExists($params['listId']) == false;
+  }
+]);
+```
+
+Inside `views/user-wishlist.graphql`, the `$listId` variable will be populated with the regular expression match from the custom route.
+
+```graphql filename="/views/user-wishlist.graphql"
+query UserWishlist($listId: String!) {
+  wishlist(id: $listId) {
+    title
+    items {
+      title
+    }
+  }
+}
+```
+
+## Generating WordPress URLs For Custom Routes [#generating-wordpress-urls-for-custom-routes]
+
+A custom route only tells `eddev` how to handle an incoming URL. If WordPress also needs to generate that URL from `get_permalink()`, GraphQL `uri` fields, menus, or block data, remap the WordPress permalink separately.
+
+For posts and custom post types, use the [`post_type_link`](https://developer.wordpress.org/reference/hooks/post_type_link/) filter. SFF uses this for Film posts: each Film still lives in WordPress as a `film` post, but generated links are rewritten based on the festival/program that owns the Film. The matching custom routes then resolve those paths back to `views/single-film.tsx`.
+
+```php filename="/backend/routes.php"
+add_filter('post_type_link', function ($link, $post) {
+  if ($post->post_type === 'film') {
+    return Programs::getPrefixForProgram($post->post_parent) . $post->post_name . "/";
+  }
+
+  return $link;
+}, 10, 2);
+```
+
+For taxonomy or category URLs, use the matching WordPress term link filter, such as `term_link` or `category_link`, with the same idea: generate the public URL you want, then add a custom route that knows how to resolve that URL into view data.
+
+## Extra Vars [#extra-vars]
+
+You can use the `extraVars` option if you need to calculate some additional GraphQL parameters based on the URL.
+
+Say you want to use `/films/{festival}/{film}/` as the pathname for Films, where film slugs are only unique to that festival. The best way to accomplish this would be to:
+
+* Disable the default item pages, using [`"rewrite" => false`](./wordpress#post-type-routing) on the Films post type
+* Use the `post_type_link` filter to ensure that Film URLs are generated correctly.
+* Add a custom route for the pattern, which handles 404s correctly.
+
+Your custom route might look something like this:
+
+```php
+ED()->addCustomRoute('films/([a-z0-9-]+)/([a-z0-9-]+)/?$', [
+  // Use the 'single-film' template by convention, even though it could be anything
+  'template' => 'views/single-film.tsx',
+  // Map the URL params -> query vars
+  'queryVars' => [
+    'festivalSlug' => "$1",
+    'filmSlug' => "$2",
+  ],
+  'extraVars' => function ($vars) {
+    global $wp_query;
+    $post = get_post([/*...*/]);
+    if (!$post) return [];
+
+    // Optionally set the global queried_object_id, so that WordPress will handle the page title/SEO metadata as normal
+    $wp_query->queried_object_id = $post->ID;
+    $wp_query->queried_object = $post;
+
+    // Return the `postId` param
+    return [
+      'postId' => $post->ID
+    ];
+  },
+  'is404' => function ($vars) {
+    return empty($vars['postId']);
+  }
+]);
+```
+
+<Callout>
+  TODO: OpenGraph Metadata
+</Callout>

package/skills/eddev/docs/routing/full-details.mdx

@@ -0,0 +1,37 @@
+# How it Works (/docs/routing/full-details)
+
+**Trace how eddev loads route data for SPA and serverless navigation.**
+
+## Route Data Handling [#route-data-handling]
+
+When navigating to a new page, the frontend router makes a request to WordPress to fetch the JSON data needed by the current route. The request is handled by the `RouteLoader` (accessible via `useRouter().loader`).
+
+The JSON data is available via `/{path}?_props=1` in SPA mode, and `/_data/route/{path}` in serverless mode.
+
+| Mode       | URL                | JSON Page                       |
+| ---------- | ------------------ | ------------------------------- |
+| Serverless | `/work/my-project` | `/_data/route/work/my-project/` |
+| SPA        | `/work/my-project` | `/work/my-project/?_props=1`    |
+
+The *serverless* mode `/_data/route/{path}` version proxies the `/{path}/?_props=1` version from the WordPress origin, but allows for additional processing, caching and (potential future) static site generation.
+
+On the WordPress side, `eddev-php` takes over, recognising that `?_props=1` is present in the URL. WordPress resolves the route that should be displayed using the [WordPress Template Hierarchy](https://developer.wordpress.org/themes/basics/template-hierarchy/) and any [Custom Routes](./custom), and identifies the `view`, or page template, that should be rendered.
+
+Once the page template has been found, `eddev-php` then looks for a paired `.graphql` file with the same name. So if `views/single-project.tsx` is resolved as the template, then it'll search for a `views/single-project.graphql` file.
+
+That GraphQL file is then executed, and the result is captured.
+
+During this process, one of the following will happen:
+
+* The route resolves to a 404 page, so the 404 view or `_error` view receives error details.
+* The GraphQL query throws an error, so the view is set to `_error` and `props` is set to the error details.
+* The GraphQL succeeds, and the process continues.
+* No GraphQL file was present, so props is set to an empty object.
+
+After this, `wp_head()`, `wp_footer()` are called, allowing WordPress (and plugins) to spit out meta tags and any other tags that should be present on the page. This HTML output is parsed, and included in the final payload.
+
+The request is then resolved with the final JSON payload.
+
+<Callout>
+  Most of this process also occurs when the page is loaded directly, but the JSON payload is instead printed in a `<script>window._PAGE_DATA = {...}</script>`, with app data also being included.
+</Callout>

package/skills/eddev/docs/routing/wordpress.mdx

@@ -0,0 +1,70 @@
+# WordPress Routing (/docs/routing/wordpress)
+
+**Let WordPress resolve URLs while React renders the matched view.**
+
+Rather than using file-based routing, we allow WordPress to serve as the 'authority' on what a given URL should display.
+
+This results in a tighter coupling between the CMS and the frontend — with a single source of truth for getting/resolving URLs, with very minimal configuration — and allows us to serve the site as both an SPA on the WordPress server (no Node.js needed), as well as a standalone SSR frontend (deployed to Vercel).
+
+The stack essentially allows the [Wordpress Template Hierarchy](https://developer.wordpress.org/themes/basics/template-hierarchy/) to unfold as normal, but it allows `.tsx` files to be used, instead of `.php` files. So, when WordPress attempts to look for `single-event.php`, it'll instead look for `views/single-event.tsx`.
+
+## Custom Routes [#custom-routes]
+
+Custom routes can be registered using the `ED()->addCustomRoute()` method in PHP. [Read More](./custom)
+
+## Post Type Routing [#post-type-routing]
+
+The code below would provide:
+
+* a listing page at `/work`, which would use `views/archive-project.tsx` as the template.
+* a page for each project at `/work/{slug}`, which would use `views/single-project.tsx` as the template.
+
+```php
+ED()->registerPostType("projects", [
+  /* ... */
+  "has_archive" => true,
+  "rewrite" => [
+    "slug" => "work",
+    "with_front" => false
+  ]
+])
+```
+
+<Callout type="info">
+  To disable the default listing page, just pass `"has_archive" => false`<br />
+  To disable the default post page, just pass `"rewrite" => false`
+</Callout>
+
+## Posts URLs without pages [#posts-urls-without-pages]
+
+Sometimes you might want to redirect a post type to another page. You can use the [post\_type\_link](https://developer.wordpress.org/reference/hooks/post_type_link/) filter to do this.
+
+```php
+ED()->registerPostType("projects", [
+  /* ... */
+  // Disable the default route, to remove it from the router
+  "rewrite" => false
+])
+
+// Return a custom URL for this post
+add_filter('post_type_link', function ($url, $post) {
+  if ($post->post_type === 'job') {
+    return "/jobs?job=".$post->post_name;
+  }
+  return $url;
+}, 10, 2);
+```
+
+<Callout type="warning">
+  Note that this doesn't affect how routes are resolved — just how links are generated.
+</Callout>
+
+<Callout type="info">
+  The same functionality can be applied to Taxonomy terms too, via [term\_link](https://developer.wordpress.org/reference/hooks/term_link/).
+</Callout>
+
+## Rule Flushing Hack [#rule-flushing-hack]
+
+WordPress caches the routing rules for performance reasons, which can sometimes result in routing updates not applying.
+
+The stack tracks custom route and post-type declarations, and automatically calls [flush\_rewrite\_rules](https://developer.wordpress.org/reference/functions/flush_rewrite_rules/) when changes are detected. If you're doing something more advanced with WordPress routing, you may need to flush the router manually. Just navigate to *Settings -> Permalinks* and simply hit *Save Changes*.

package/skills/eddev/docs/routing.mdx

@@ -0,0 +1,18 @@
+# Routing Overview (/docs/routing)
+
+**Understand the WordPress and frontend sides of eddev routing.**
+
+There are two sides to routing in our stack:
+
+1. **WordPress/PHP** — We allow WordPress to act as the authority on routing, and the stack provides extra functions for extending this.
+2. **Frontend API** — The `eddev` library provides JavaScript APIs for handling client-side navigation, and for preloading data and components.
+
+<Cards>
+  <Card title="WordPress Routing" href="/routing/wordpress">
+    Let WordPress resolve URLs while React renders the matched template.
+  </Card>
+
+  <Card title="Frontend APIs" href="/routing/api">
+    Use eddev link and router APIs for client-side navigation.
+  </Card>
+</Cards>

package/skills/eddev/docs/serverless/functions.mdx

@@ -0,0 +1,436 @@
+# RPC Functions (/docs/serverless/functions)
+
+**Define TypeScript RPC routes for serverless eddev projects.**
+
+Serverless functions are TypeScript HTTP routes that allow you to build REST endpoints.
+
+To get started:
+
+* You'll need to create a `server/routes/` folder
+* You'll also need to install [`zod`](https://zod.dev/) via `yarn add zod`. Zod is used for validation of RPC inputs.
+
+The `server/routes` folder contains a set of `.ts` files, and uses file-based routing. You can also create an optional `server/_context.ts` file, which allows you to parse HTTP headers for things like auth, and pass additional information to your API handlers.
+
+Each file must have a `default` export, and export either a [query](#queries), [mutation](#mutations), or a [router](#routers).
+
+You can also add additional helper code anywhere in the `server` folder, and it'll be ignored — as long as it's not in the `server/routes` folder. Of course, you can also import code from elsewhere in your project.
+
+An example folder structure:
+
+<Files>
+  <Folder name="server/">
+    <File name="_context.ts" />
+
+    <Folder name="routes/">
+      <File name="api.pokemon.ts" />
+
+      <File name="api.echo.ts" />
+
+      <Folder name="api/">
+        <Folder name="users/">
+          <File name="auth.ts" />
+
+          <File name="prefs.ts" />
+        </Folder>
+      </Folder>
+    </Folder>
+
+    <Folder name="lib/">
+      <File name="whatever.ts" />
+    </Folder>
+  </Folder>
+</Files>
+
+<Callout type="info">
+  Under the hood, the stack uses [tRPC](https://trpc.io) to define server-side procedures and routers, with custom eddev integration. You should familiarize yourself with the core concepts of procedures, routing and context in tRPC, but examples are shown on this page. You don't need to install tRPC, as it's included in the stack.
+</Callout>
+
+<Callout type="warning">
+  RPC functions require a Vercel deployment. The [`useRPCQuery()`](#userpcquery) and [`useRPCMutation()`](#userpcmutation) hooks will work correctly in WordPress admin and the SPA frontend, as long as the `serverless.endpoints` object in `ed.config.json` is configured correctly — it must contain a mapping of the WordPress origin to the serverless endpoint, for example `"cms.ed.studio": "ed.studio"`.
+</Callout>
+
+## Defining Routes [#defining-routes]
+
+Routes are defined using file-based routing. You can use a combination of folders and filenames with `.` so `api/hello.ts` and `api.hello.ts` do the same thing! It's recommended that you use `api.hello.ts` so that your filenames are easier to search for and recognise in your code editor.
+
+Below are some examples of how the file-based routing is resolved:
+
+<table>
+  <thead>
+    <tr>
+      <th>
+        File
+      </th>
+
+      <th>
+        URL Path
+      </th>
+
+      <th>
+        Notes
+      </th>
+    </tr>
+  </thead>
+
+  <tbody>
+    <tr>
+      <td>
+        `/routes/demo1.ts`
+      </td>
+
+      <td>
+        `/demo1`
+      </td>
+
+      <td>
+        Straight-up file -> URL
+      </td>
+    </tr>
+
+    <tr>
+      <td>
+        `/routes/api/tickets.ts`
+      </td>
+
+      <td>
+        `/api/tickets/`
+      </td>
+
+      <td>
+        Using folders
+      </td>
+    </tr>
+
+    <tr>
+      <td>
+        `/routes/api.tickets.ts`
+      </td>
+
+      <td>
+        `/api/tickets/`
+      </td>
+
+      <td>
+        Using filenames only with `.` instead of folders
+      </td>
+    </tr>
+
+    <tr>
+      <td>
+        `/routes/api/hubspot.forms.ts`
+      </td>
+
+      <td>
+        `/api/hubspot/forms/`
+      </td>
+
+      <td>
+        Using a combination of folders + `.` syntax
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+## Procedures [#procedures]
+
+"Procedures" are either "queries" or "mutations". Queries are GET requests, and mutations are POST requests. Both have a nearly identical syntax, but are called in different ways.
+
+Multiple procedures can be contained within a single file by exporting a ["router"](#routers).
+
+### Queries [#queries]
+
+Query procedures use the `GET` HTTP method.
+
+```typescript filename="/server/routes/api.getPokemon.ts"
+import { rpc } from "eddev/server"
+import { z } from "zod"
+
+export default rpc.procedure
+  .input(
+    z.object({
+      name: z.string().min(2),
+    }),
+  )
+  .query(async ({ ctx, input }) => {
+    const response = await fetch(`https://pokeapi.co/api/v2/pokemon/${input.name}`)
+    const data = await response.json()
+
+    return {
+      pokemonInfo: data,
+    }
+  })
+```
+
+#### `useRPCQuery()` [#userpcquery]
+
+In React, you can then call `useRPCQuery` with the name `"api.getPokemon"` and type-safe arguments, and observe the result.
+
+```tsx filename="PokemonInfo.tsx"
+import { useRPCQuery } from "eddev/hooks"
+
+type Props = {
+  name: string
+}
+
+export function Pokemon(props: Props) {
+  const pokemon = useRPCQuery("api.getPokemon", { name: props.name })
+
+  if (pokemon.isSuccess) {
+    return (
+      <div>
+        Pokemon data: <pre>{JSON.stringify(pokemon.data.pokemonInfo, null, 2)}</pre>
+      </div>
+    )
+  } else if (pokemon.isLoading) {
+    return <div>Loading...</div>
+  } else if (pokemon.isError) {
+    return <div>Error: {pokemon.error.message}</div>
+  }
+}
+```
+
+<Callout>
+  The return result of `useRPCQuery` is the same as our generated GraphQL hooks. It also accepts a third argument, the query options, where you can pass options like `refetchInterval` to have the hook auto-refresh. See [TanStack docs for useQuery](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery)
+</Callout>
+
+#### `rpcClient.query()` [#rpcclientquery]
+
+You can also call queries procedurally using `rpcClient.query()`, like so:
+
+```typescript
+const bulbasaur = await rpcClient.query("api.getPokemon", { name: "bulbasaur" })
+console.log("Bulbasaur is", bulbasaur)
+```
+
+### Mutations [#mutations]
+
+Use `mutation` procedures for actions that should be triggered when a user completes an action, like submitting a form.
+
+Mutations will be called from React with `const mutation = useRPCMutation("api.submit")` and `mutation.mutate(args)`
+
+```typescript filename="/server/routes/api.subscribe.ts"
+import { rpc } from "eddev/server"
+import { z } from "zod"
+
+export default rpc.procedure
+  .input(
+    z.object({
+      email: z.string(),
+      listId: z.string()
+    }),
+  )
+  .mutation(async ({ input }) => {
+    const params = new URLSearchParams()
+    params.append("EMAIL", input.email)
+    params.append("id", input.listId)
+    const response = await fetch(`${env.CAMPAIGN_MONITOR_URL}&${params}`, {
+      method: "GET",
+    })
+    if (response.ok) {
+      return { success: true }
+    } else {
+      return { success: false }
+    }
+  })
+```
+
+#### `useRPCMutation()` [#userpcmutation]
+
+In React, you can then call `useRPCMutation` with the name `"api.subscribe"` and type-safe arguments, and observe the result.
+
+```tsx filename="SignupForm.tsx"
+import { useRPCMutation } from "eddev/hooks"
+import { useState } from "react"
+
+type Props = {
+  listId: string
+}
+
+export function SignupForm(props: Props) {
+  const [email, setEmail] = useState("")
+  const subscribe = useRPCMutation("api.subscribe")
+
+  if (subscribe.isSuccess) {
+    console.log("Result is", subscribe.data)
+    return <div>Thank you for signing up!</div>
+  }
+
+  return <form onSubmit={e => {
+    e.preventDefault()
+    subscribe.mutate({ email: email, listId: props.listId })
+  }}>
+    {/* Error message */}
+    {subscribe.isError && <p>{subscribe.error.message}</p>}
+    {/* Disable input when submitting */}
+    <input type="email" disabled={subscribe.isPending} value={email} onChange={e => setEmail(e.currentTarget.value)} />
+    <button type="submit">Submit</button>
+  </form>
+}
+```
+
+<Callout>
+  The return result of `useRPCMutation` is the same as our generated GraphQL hooks. It also accepts a second argument, the mutation options, where you can pass options like `onSuccess` to trigger functions to occur after successful submission. See [TanStack docs for useMutation](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation)
+</Callout>
+
+#### `rpcClient.mutation()` [#rpcclientmutation]
+
+You can also call mutations procedurally using `rpcClient.mutation()`, like so:
+
+```typescript
+const result = await rpcClient.mutation("api.subscribe", { email: "hello@internet.com", listId: "12345" })
+console.log("Sign up result", result)
+```
+
+## Routers [#routers]
+
+Multiple procedures can be exported from a single file by exporting a "router". A router mounts multiple endpoints at once. Use `rpc.router()` when you have a group of highly-related API functions.
+
+```typescript filename="/server/routes/api.math.ts"
+import { rpc } from "eddev/server"
+import z from "zod"
+
+export default rpc.router({
+  sum: rpc.procedure
+    .input(
+      z.object({
+        a: z.number(),
+        b: z.number(),
+      }),
+    )
+    .query(({ input }) => {
+      return input.a + input.b
+    }),
+  random: rpc.procedure.query(() => {
+    return Math.random()
+  }),
+  pi: rpc.procedure.query(() => {
+    return Math.PI
+  }),
+})
+```
+
+Procedures defined in a router can be called using [`useRPCQuery()`](#userpcquery) and [`useRPCMutation()`](#userpcmutation), like any other procedure.
+
+```tsx
+import { useRPCQuery } from "eddev/hooks"
+
+export function Demo() {
+  const pi = useRPCQuery("api.math.pi")
+  const random = useRPCQuery("api.math.random")
+
+  const sum = useRPCQuery(
+    "api.math.sum",
+    { a: pi.data ?? 0, b: random.data ?? 0 },
+    {
+      enabled: pi.isSuccess && random.isSuccess,
+    },
+  )
+
+  return (
+    <div>
+      <div>Pi: {pi.data}</div>
+      <div>Random: {random.data}</div>
+      <div>Sum: {sum.data}</div>
+    </div>
+  )
+
+}
+```
+
+## Context Middleware [#context-middleware]
+
+The `/server/_context.ts` file is optional, but can be defined to extract common metadata from a request. You can use it to parse Auth headers or cookies, and the returned values will be available in the `ctx` argument of your procedures.
+
+```typescript filename="/server/_context.ts"
+import { defineServerContext } from "eddev/server"
+
+export default defineServerContext((ctx) => {
+  const headers = ctx.req.headers
+  return {
+    ...ctx,
+    user: {
+      ip: headers.get("x-real-ip") ?? headers.get("x-real-ip") ?? "",
+    },
+  }
+})
+```
+
+You'll need to run `eddev dev` to ensure that the TypeScript types are generated at least once. In any procedure, you can now access `ctx.user.ip`.
+
+```typescript filename="/server/api.ip.ts"
+import { rpc } from "eddev/server"
+
+export default rpc.procedure.query(async ({ ctx }) => {
+  return {
+    ip: "Your IP is " + ctx.user.ip,
+  }
+})
+```
+
+## Connecting to WordPress [#connecting-to-wordpress]
+
+[Generated GraphQL hooks](/docs/graphql/query-hooks) can be called using `.fetch()` and `.mutate()`, with arguments.
+
+```typescript
+import { rpc } from "eddev/server"
+
+export default rpc.procedure
+  .query(async ({ ctx, input }) => {
+    const data = useLatestNews.fetch({ category: "design" })
+
+    return {
+      latest: data.news.nodes[0]
+    }
+  })
+```
+
+## Non-RPC Responses [#non-rpc-responses]
+
+RPC queries typically return JSON payloads with a `Content-Type: application/json` header, however procedures can also be used as generic HTTP endpoints, by simply returning a native JavaScript `Response` object. Note that this will only work on Vercel-deployed domains.
+
+```typescript
+import { rpc } from "eddev/server"
+
+export default rpc.procedure.query(async () => {
+  return new Response("Hello world", {
+    status: 200,
+    headers: {
+      "Content-Type": "text/plain",
+      "Cache-Control": "max-age=3600, s-maxage=3600, public",
+    },
+  })
+})
+```
+
+<Callout>
+  Note that when returning a `Response` object, the procedure may no longer be callable with `useRPCQuery()` and `useRPCMutation()`, since it may no longer conform to tRPC's return protocol.
+</Callout>
+
+There are also some helper methods for force-rendering pages from other routes.
+
+The `renderPage()` function can be used to display a page with a specific route. This should be avoided in the majority of cases.
+
+```typescript
+import { rpc, renderPage } from "eddev/server"
+
+export default rpc.procedure.query(async () => {
+  return renderPage({
+    pathname: "/",
+  })
+})
+```
+
+Similarly, the `renderErrorPage()` function can be used to display the site's standard error page.
+
+```typescript
+import { renderErrorPage, rpc } from "eddev/server"
+
+export default rpc.procedure.query(async () => {
+  const result = await renderErrorPage({
+    title: "Bad Request",
+    statusCode: 400,
+    userMessage: "Something went wrong",
+  })
+  return result
+})
+```