eddev 0.2.20 → 0.2.23

package/docs_old/docs/how-to/5.bundle-size.md

@@ -0,0 +1,177 @@
+# Bundle Size Tips
+
+## Inspecting Bundle Size
+
+You can quite easily see the production size of your app by running:
+
+```bash
+yarn build
+```
+
+![Webpack Result](./img/bundle-webpack-before.png)
+
+Above, we can see that the bundle size is 1.34mb, which is quite large. The note from Webpack says that we should aim for 244kb, which is really quite small. When we eventually move to serverless (via Vercel) for production frontends, we'll certainly aim for this smaller size. For now, with WordPress hosting, 600-700kb is fine. React itself takes up a bit of space on it's own.
+
+Let's dig deeper into why the bundle is so large.
+
+Our compile system includes the official [Webpack Bundle Analyzer](https://www.npmjs.com/package/webpack-bundle-analyzer) plugin. You can get a detailed analysis of the bundle size using the following:
+
+```bash
+yarn build
+open dist/frontend/bundle-report.html
+```
+
+Your browser will launch the bundle report, which will look something like this.
+
+![Bundle Size Output](./img/bundle-analysis-before.png)
+
+You can see in the example above, that `hls.js` and `moment` + `moment-timezone` are taking up _a lot_ of the bundle size.
+
+What can we do about this?
+
+## Choosing better libraries
+
+In the example above, `moment` is taking up SO much space, for something that is so simple. There are much simpler and smaller libraries that can be used instead.
+
+- If all you want is date formatting, check out `date-fns` — which provides a nifty date formatting function. The library is tree-shakable, meaning only the functions from that library you actually use in your code will be included in the bundle. [date-fns →](https://date-fns.org/)
+- If you need something a little more powerful, or if you need something related to timezones, check out `luxon`, which is made by the same team that created `moment`. It's a much lighter alternative, because even though it supports timezones, it uses native browser APIs, instead of bundling info on every timezone/locale. [Luxon →](https://moment.github.io/luxon/index.html#/?id=luxon)
+  - (ps. Luxon doesn't come with TypeScript types, but you can install them using `yarn add --dev @types/luxon`)
+
+It's always worth reconsidering the libraries we choose, looking for the most modern libraries for certain functions.
+
+## Dynamic imports
+
+Next up is `hls.js`. It's a library that provides a simple way to load and play HLS streams. It's not huge, but we probably don't need to include it in the main bundle.
+
+Say we have the following code:
+
+```tsx
+import Hls from "hls.js"
+
+// ...
+
+useEffect(() => {
+  const video = ref.current!
+  if (src) {
+    if (video.canPlayType("application/vnd.apple.mpegurl")) {
+      // HLS is already supported natively by this browser
+      video.src = props.url
+    } else {
+      // HLS is not supported by the browser. Use Hls.js instead!
+      const hls = new Hls()
+      hls.loadSource(props.url!)
+      hls.attachMedia(video)
+      return () => {
+        hls.destroy()
+      }
+    }
+  }
+}, [src])
+```
+
+We can quite easily refactor this code to use dynamic imports, which will automatically split that library into it's own file, which will be imported separately only if/when it's needed. If we still need TypeScript types for the module, we can also use `import type` syntax, which will only import the types for TypeScript's sake, and not the module itself.
+
+```tsx
+import type Hls from "hls.js"
+
+// ...
+
+useEffect(() => {
+  const video = ref.current!
+  if (props.url) {
+    if (video.canPlayType("application/vnd.apple.mpegurl")) {
+      // HLS is already supported natively by this browser
+      video.src = props.url
+    } else {
+      // HLS is not supported by the browser. Use Hls.js instead!
+      // Declare a reference to the object, so we can can still destroy it when the component transitions out
+      let hls: Hls
+      import("hls.js").then(({ default: Hls }) => {
+        // hls.js has been successfully dynamically imported.
+        // Assign to the `hls` variable, so that it can be destroyed properly
+        hls = new Hls()
+        hls.loadSource(props.url!)
+        hls.attachMedia(video)
+      })
+      return () => {
+        // Destroy the hls video, as long as it was created in the first place
+        if (hls) {
+          hls.destroy()
+        }
+      }
+    }
+  }
+}, [props.url])
+```
+
+## Dynamicly imported components
+
+Similar to Next's `next/dynamic` [(link)](https://nextjs.org/docs/advanced-features/dynamic-import), we have our own `eddev/dynamic` function. This allows you dynamically load components from the `components/*` directory using dynamic imports.
+
+```tsx title="blocks/homepage/some-block.tsx"
+import { dynamic } from "eddev/dynamic"
+
+const MyDynamicComponent = dynamic(() => import("@components/something/my-dynamic-component"))
+
+export default defineBlock("homepage/some-block", () => {
+  return (
+    <div>
+      <p>I appear instantly</p>
+      <MyDynamicComponent fallback={<div>Loading...</div>} />
+    </div>
+  )
+})
+```
+
+All the same props from `MyDynamicComponent` are available, and the fallback (which is optional) is added as a prop by the `dynamic` function. It'll show the fallback while the component is loading.
+
+When using this feature, you may notice a flash while the component is being loaded, since your page will actually render without the dynamic component first. This means that it may not always be suitable if the component is typically "above the fold". You may want to consider showing a placeholder div, and/or fading in the component using an animation once it's loaded.
+
+It's also important to note that the dynamic function expects (by default), a `default` export. Normally, we prefer to export named components, but in this case, `default` is good.
+
+```tsx title="components/something/my-dynamic-component.tsx"
+// BAD: export function MyDynamicComponent() {}
+// GOOD:
+export default function MyDynamicComponent() {
+  return <div>I'm a dynamic component!</div>
+}
+```
+
+Internally, we use `@loadable/components` — you can see other options for `dynamic` via their [docs](https://loadable-components.com/). Next also uses this library!
+
+## Dynamically imported blocks
+
+The `eddev/dynamic` function requires a tiny bit of boilerplate to get going. If you'd like to make a whole _block_ load dynamically, it's even easier. Note though that you wont be able to show a loading fallback.
+
+Just add `Dynamic: true` to your block header comment — the compiler will spot this, and automatically turn it into a dynamic component. That's it!
+
+```tsx title="blocks/homepage/some-block.tsx"
+/**
+ * Title: Some Block
+ * Description: A block that does something cool
+ * Category: common
+ * Icon: book-alt
+ * Keywords: post
+ * Templates: default
+ * Types: page
+ * Mode: preview
+ * Supports multiple: true
+ * Tags: root
+ * Child Tags: none
+ * Dynamic: true
+ */
+```
+
+^ The last line is the important part. You can read more about dynamic blocks [here](../gutenberg/dynamic-blocks).
+
+## Validating the changes
+
+In the top sections above, we swapped from `moment` to `luxon`, and we also made `hls.js` a dynamic import.
+
+After running `yarn build` again, and checking out the visualizer, we can see that these two small changes have reduced our main bundle size by **HALF**.
+
+![Webpack Result](./img/bundle-webpack-after.png)
+
+![Bundle Size Output](./img/bundle-analysis-after.png)
+
+We could take this even further if we wanted, by making any blocks which use Swiper dynamic blocks, as discussed above.

package/docs_old/docs/how-to/6.favicons.md

@@ -0,0 +1,82 @@
+# Favicons
+
+Since `eddev@0.2.0`, favicons are automatically included in every page, in both serverless and WordPress. All you need to do is export the icons straight from Figma!
+
+## Exporting the icons
+
+1. Navigate to the **🍒 oGraph & Icons** page in Figma
+2. Select all the icons on the right
+3. Activate the **Export** tab in the sidebar
+4. Export with default settings to the `assets` folder in your theme.
+5. Run `yarn dev` to regenerate the `favicon.ico` file, which is used as a fallback. The `<head>` is published automatically.
+
+:::tip
+See the bottom of this page for screenshots!
+:::
+
+## `favicon.ico`
+
+When you run `yarn dev` or `yarn build`, a `favicon.ico` is automatically generated for you!
+
+It uses the uses the pattern `assets/favicon/favicon-*.png`, which usually means it'll be composed using `favicon-16x16.png`, `favicon-32x32.png` and `favicon-96x96.png`.
+
+## Light & Dark Mode Icons
+
+Not all browsers support SVG favicons, but they're a great way to optionally support light/dark mode. You can right-click and 'Copy as SVG', and then add appropriate styling. Save to `assets/favicon/favicon.svg`, and it'll automatically be added to the `<head>` tag.
+
+See below for an example:
+
+```svg title="assets/favicon/favicon.svg"
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none"
+  xmlns="http://www.w3.org/2000/svg">
+  <style>
+    path {
+      fill: #000000;
+    }
+    @media (prefers-color-scheme: dark) {
+      path {
+        fill: #ffffff;
+      }
+    }
+  </style>
+  <path d="..." />
+</svg>
+```
+
+## Meta Tags
+
+The appropriate `<link />` tags are automatically added to your `<head>` tag, so you don't need to worry about it. Note that these tags only appear if they're found in the correct folder (`assets/favicon/`).
+
+## Filenames
+
+The following files are expected to be found. Note that if they are missing, there are no errors!
+
+```
+/assets/favicons/favicon.svg
+/assets/favicons/120x120.png
+/assets/favicons/128x128.png
+/assets/favicons/196x196.png
+/assets/favicons/apple-touch-icon-120x120.png
+/assets/favicons/apple-touch-icon-152x152.png
+/assets/favicons/apple-touch-icon-167x167.png
+/assets/favicons/apple-touch-icon-180x180.png
+/assets/favicons/favicon-16x16.png
+/assets/favicons/favicon-32x32.png
+/assets/favicons/favicon-96x96.png
+/assets/favicons/windows-270x270.png
+/assets/favicons/windows-70x70.png
+```
+
+## Screenshots of export steps
+
+Select all the icons, skipping the labels:
+
+![Figure A. Select all icons](./img/favicon-figma.png)
+
+Export your selection:
+
+![Figure B. Export them](./img/favicon-figma-export.png)
+
+Your codebase should look like this after you've exported them. Note that if you instead see an `App icon` folder, you should rename this to `favicon` and ensure that it matches as below:
+
+![Figure C. You should now have a 'favicons' folder](./img/favicon-codebase.png)

package/docs_old/docs/how-to/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "🧐 How To",
+  "position": 20
+}

package/docs_old/docs/intro.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 1
+---
+
+# 👋 Intro
+
+Welcome! Use the sidebar on the left to find what you're looking for.

package/docs_old/docs/known-issues.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 100
+---
+
+# Known Issues
+
+- Fragments from `/queries/fragments` don't run in GraphiQL IDE
+- Block ACF fields cannot be queried in the GraphiQL IDE

package/docs_old/docs/serverless/1.overview.md

@@ -0,0 +1 @@
+# Overview

package/docs_old/docs/serverless/2.config.md

@@ -0,0 +1 @@
+# Config

package/docs_old/docs/serverless/3.wordpress-vercel.md

@@ -0,0 +1,8 @@
+# WordPress + Vercel
+
+WIP
+
+- `SITE_URL` environment variable in Vercel
+- `serverless.endpoints` option in `ed.config.json` — so that:
+  - Frontend code executed in WordPress can access API endpoints hosted on Vercel
+  - WordPress can redirect to the Vercel URL if WordPress is being used completely headless

package/docs_old/docs/serverless/4.apis.md

@@ -0,0 +1 @@
+# APIs

package/docs_old/docs/serverless/5.rpc.md

@@ -0,0 +1 @@
+# RPC API

package/docs_old/docs/serverless/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "☀️ Serverless",
+  "position": 5
+}

package/docs_old/docs/stack/1-WordPress.md

@@ -0,0 +1,18 @@
+---
+sidebar_position: 1
+---
+
+# WordPress
+
+There are several CMS' out there, and while WordPress may not be the most modern, it's very well known (both to clients and developers) and is easy to work with and host.
+
+## Why not a cloud-based headless CMS + Next.js?
+
+We use WordPress as a semi-headless CMS. While there are plenty of cloud-based headless CMS' out there, there are several issues with using them:
+
+- They can be quite expensive!
+- They often lack features we require, such as versioning, translation, ecommerce, user registration, user-submitted data, live preview and block-based content editing. These features are also often hidden behind an expensive 'Enterprise' plan.
+- The lack of specific features often leads to the requirement of additional third-party platforms, which adds a great deal of complexity to our projects.
+- Integrating them with frameworks like Next.js require lots of boilerplate code, which becomes hard to maintain.
+- Next.js' file-based routing is great for web apps, but imposes limitations on URL customisation which are hard to overcome.
+- We love our elegant page transitions, and these are harder to achive with Next.js.

package/docs_old/docs/stack/2-Flywheel.md

@@ -0,0 +1,15 @@
+---
+sidebar_position: 2
+---
+
+# Flywheel + Local
+
+Our primary WordPress hosting provider is [Flywheel](https://getflywheel.com/). We have an organisation plan which allows us to host hundreds of WordPress sites, managed in an easy-to-use [dashboard](https://app.getflywheel.com/).
+
+[Local](https://localwp.com/) is a desktop app which provides a development environment for WordPress sites, and was developed by Flywheel. It has useful 'sync' functionality, allowing you to push/pull files and the database between Local and a Flywheel site.
+
+## Local Sync
+
+Feel free to use Local Sync to deploy your WordPress site to Flywheel during the initial stages of development, however it's recommended that you use Github Actions to automate code deployment.
+
+Pulling from Flywheel to Local is also a great way to pull down a site to work on it locally — just don't forget to re-clone the theme folder so that it's correctly linked to Git.

package/docs_old/docs/stack/3-React.md

@@ -0,0 +1,12 @@
+---
+sidebar_position: 3
+---
+
+# React
+
+There's not much to say! React is great. It's particularly great for complex UI.
+
+Be sure you're across React, hooks and how to use TypeScript with React. You should also probably know how Context works
+
+- [React Hooks Guide on Smashing Magazine](https://www.smashingmagazine.com/2020/04/react-hooks-api-guide/) — goes over all the core hooks, as well as how to create custom hooks.
+- [React & TypeScript: how to type hooks (a complete guide)](https://devtrium.com/posts/react-typescript-how-to-type-hooks) — learn by looking! Lots of examples and tips on how to correctly use hooks with TypeScript.

package/docs_old/docs/stack/4-TypeScript.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 4
+---
+
+# TypeScript
+
+TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. We use TypeScript to write code that is easier to read and understand, although it is not as fast as JavaScript.
+
+Some resources:
+
+- [TypeScript — The Basics](https://www.youtube.com/watch?v=ahCwqrYpIuM) (video)
+- [TypeScript with React](https://www.notion.so/ed-studio/ED-Stack-2021-Tour-7f50bc455d95403ebdff9a4503a78aee#b15ee6c11d40449e8f18b9ff19301901) (Udemy course)
+- [React & TypeScript: how to type hooks (a complete guide)](https://devtrium.com/posts/react-typescript-how-to-type-hooks) — learn by looking! Lots of examples and tips on how to correctly use hooks with TypeScript.

package/docs_old/docs/stack/5-WPGraphQL.md

@@ -0,0 +1,21 @@
+# (WP)GraphQL
+
+"GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools." (from the [GraphQL Website](https://graphql.org/)).
+
+The [WPGraphQL](https://www.wpgraphql.com/) plugin (which is actually installed in the theme with Composer, rather than a plugin), provides a GraphQL API for WordPress.
+
+## Schemas
+
+GraphQL requires a server to be running to serve the queries. The WPGraphQL plugin provides a server that can be accessed at the URL `/graphql`, or via the `graphql()` PHP function.
+
+The schema is automatically generated for you by the plugin, and makes all WordPress data available to you via queries.
+
+You can define your own types and fields on the schema using the PHP functions documented on the [WPGraphQL website](https://www.wpgraphql.com/functions/).
+
+## Queries
+
+Queries are written in `.graphql` files, which can be stored in three locations in your code.
+
+- `blocks/*/*.graphql`, alongside a block's `.tsx` file. Queries in these files will be run automatically by the server when the page is visited, and the data is passed as props to the block component. This allows blocks to query any other data on the site. Blocks can also query ACF fields defined on the block, via the global `block` field, which represents the current block being executed.
+- `views/*.graphql`, alongside any View `.tsx` file. Just like blocks, the data is passed to the view's component. They can also use special variables to refer to the current post, or some querystring value.
+- `queries/*.graphql`— these queries will have React hooks automatically generated for them, allowing the queries or mutations to be executed on demand by your React code. This is useful for components which need to perform searching/filtering/pagination, handle user data submissions, trigger server-side code etc.

package/docs_old/docs/stack/6-eddev.md

@@ -0,0 +1,9 @@
+# `eddev` Library
+
+## Purpose
+
+TBA
+
+## Features
+
+TBA

package/docs_old/docs/stack/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "📚 The Stack",
+  "position": 1
+}

package/docs_old/docs/tooling/1.scripts.md

@@ -0,0 +1,25 @@
+# Scripts
+
+## `yarn dev`
+
+The 'dev' command provides hot-reloading for multiple bundles — like frontend, admin and (eventually) serverless.
+
+It's custom built, and made to be as clean as possible by showing issues relevant to the most recent attempt at a rebuild.
+
+### Webpack
+
+Internally, the system uses [Webpack](https://webpack.js.org/) and [webpack-dev-server](https://webpack.js.org/configuration/dev-server/), along with [react-refresh](https://github.com/pmmmwh/react-refresh-webpack-plugin). Webpack configuration is _not editable_, and is auto-generated by the tool itself. We may swap Webpack out for another tool such as `swc` or `esbuild` at some point in the future for an additional speed boost, and so allowing access to Webpack config could result in compatibility issues.
+
+For speed, each Webpack bundle runs in a separate worker thread, so that each bundle can compile concurrently, taking advantage of multiple CPU cores.
+
+### GraphQL Codegen
+
+The dev tool also provides realtime GraphQL -> TypeScript generation, by monitoring your project for changes and rebuilding when appropriate. For this, we're using [GraphQL Code Generator](https://www.graphql-code-generator.com/) with a host of custom plugins.
+
+These files are _only_ generated by the dev tool, and not be the `yarn build` tooling. This only really matters for dynamic queries in the `queries/` folder. To be safe, you should always make sure `yarn dev` runs after editing a `.graphql` file in your project.
+
+## `yarn build`
+
+This produces production builds of the frontend and admin bundles, with tree shaking, minification and code-splitting.
+
+It also produces a bundle sizing report, in `/dist/frontnend/bundle-report.html` — which you can use to see which dependencies are bloating up your bundle files. If a dependency is too large, consider dynamically importing it instead.

package/docs_old/docs/tooling/2.aliases.md

@@ -0,0 +1,13 @@
+# Aliases
+
+There are a few import aliases predefined for you.
+
+```
+@components/* -> ./components/*
+@hooks/*      -> ./hooks/*
+@utils/*      -> ./utils/*
+@theme        -> ./theme.css.tsx
+@queries      -> ./hooks/queries.ts
+```
+
+This just means that you can use absolute paths to import your components and hooks etc, rather than having to use relative paths — making copy/pasting of import statements around your codebase a little bit easier.

package/docs_old/docs/tooling/3.defines.md

@@ -0,0 +1,13 @@
+# Defines
+
+There are a few globally accessible variables which you can access, which are defined via Webpack's `DefinePlugin`
+
+From [Webpack configuration docs](https://webpack.js.org/plugins/define-plugin/):
+
+> The `DefinePlugin` replaces variables in your code with other values or expressions at compile time. This can be useful for allowing different behavior between development builds and production builds. If you perform logging in your development build but not in the production build you might use a global constant to determine whether logging takes place. That's where DefinePlugin shines, set it and forget it rules for development and production builds.
+
+The following variables are available:
+
+- `process.dev` — `true` or `false`, depending on whether this bundle is targetting at dev mode or not.
+- `process.admin` - `true` or `false`, depending on whether this bundle is used for the admin editor (Gutenberg) or on the frontend. Useful for rendering blocks for better editing experience.
+- `process.themePath` - The relative URI pointing to the theme directory. Useful for calculating the location of assets. Note that there is NO trailing slash.

package/docs_old/docs/tooling/4.config-file.md

@@ -0,0 +1,14 @@
+# Config File
+
+You'll find a `ed.config.json` file in the root of your theme folder. This file is read by both the `eddev` dev and build tool, along with the supporting `eddev-php` library.
+
+Here are the options:
+
+- `serverless` — An optional object.
+  - `enabled` — `true` or `false` — Controls whether serverless node is enabled for this project.
+  - `uploads` — `"proxy"` or `"remote"`
+  - `plugins` — `"proxy"` or `"remote"`
+  - `theme` — `"proxy"`, `"remote"` or `"copy"`
+  - `devAssets` — an optional array of glob paths or file names, relative to the theme folder, which are necessary for the frontend — this includes `assets/**` by default.
+
+You can also find the original schema file [here](https://github.com/ed-digital/eddev/blob/main/src/config/config-schema.ts).

package/docs_old/docs/tooling/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "🛠 Tooling",
+  "position": 2
+}

package/docs_old/docs/views/1.overview.md

@@ -0,0 +1,31 @@
+# Views Overview
+
+Views represent the different page types of the site. WordPress will choose which view to use based on the URL of the page. If for example, it identifies that the url `/blog/my-first-post` is a "post" object, it'll first look for `views/single-post.tsx`, followed by `views/single.tsx`. If it doesn't find either of those, it'll use `views/_404.tsx`. The naming of view files follows WordPress' [Template Hierarchy](https://developer.wordpress.org/themes/basics/template-hierarchy/).
+
+Views exist within the `views` directory as `.tsx` files, often with a paired `.graphql` file.
+
+The standard `views/page.tsx` looks like this:
+
+```tsx title="views/page.tsx"
+import { Heading } from "@components/atoms/Heading"
+import { Container } from "@components/layout/Grid"
+import { defineView } from "eddev/views"
+import { ContentBlocks } from "eddev"
+
+export default defineView("page", (props) => {
+  return (
+    <Container>
+      <Heading variant="h1" css={{ pb: "$6" }}>
+        {props.page?.title}
+      </Heading>
+      <ContentBlocks blocks={props.page?.contentBlocks} />
+    </Container>
+  )
+})
+```
+
+You'll notice above the following:
+
+- The file exports a view defined with the `defineView` function, and the first argument passed to it is the name of the view. This MUST be consistent with the name of the file. The general rule is `views/{name}.tsx`. We just care about the name part!
+- We're getting some data from props — `props.page.title` and `props.page.contentBlocks`. These are coming from the linked query file (see the next section)
+- The code itself is quite lean. It wouldn't be strange to have a more complex file, but in general it's better to move as much code as possible into separate component files. This encourages reusability and makes it easier to maintain.

package/docs_old/docs/views/2.queries.md

@@ -0,0 +1,18 @@
+# View Queries
+
+Views typically need to access data about the current page or object, as well as other arbitrary content from the CMS. To do so, create a `.graphql` file with the same name as the `.tsx` file. The GraphQL query will be executed every request, and the data is automatically passed to the view when it is rendered. You never need to handle the loading process yourself!
+
+To query the current page or post being viewed, use `$postId` as an input variable.
+
+```graphql title="views/page.graphql"
+query Page($postId: ID!) {
+  page(id: $postId, idType: DATABASE_ID) {
+    title
+    slug
+    template {
+      templateName
+    }
+    contentBlocks
+  }
+}
+```

package/docs_old/docs/views/3.content-blocks.md

@@ -0,0 +1,36 @@
+# Content Blocks
+
+To allow Gutenberg blocks on your page, you'll need to do two things:
+
+1. Ensure you've got a `.graphql` file which selects the `contentBlocks` field from the your post type.
+2. Pass the `contentBlocks` field to the `blocks` prop of the `<ContentBlocks />` component.
+
+The `ContentBlocks` component is much like `InnerBlocks`, except that blocks are passed in as an array, rather than implictly.
+
+```graphql title="views/page.graphql"
+query Page($postId: ID!) {
+  page(id: $postId, idType: DATABASE_ID) {
+    title
+    slug
+    template {
+      templateName
+    }
+    contentBlocks
+  }
+}
+```
+
+```tsx title="views/page.jsx"
+import { Container } from "@components/layout/Grid"
+import { defineView } from "eddev/views"
+import { ContentBlocks } from "eddev"
+
+export default defineView("page", (props) => {
+  return (
+    <Container>
+      <h1>{props.title!}</h1>
+      <ContentBlocks blocks={props.page?.contentBlocks} />
+    </Container>
+  )
+})
+```

package/docs_old/docs/views/4.app-view.md

@@ -0,0 +1,35 @@
+# 'App' View
+
+The `views/_app.tsx` view is a special kind of view. It's always rendered, as the wrapper around your entire frontend. It's usually where you'd put your header/footer and other global elements, as well as where you'll load global styles.
+
+```tsx
+import { PageLoadIndicator } from "@components/generic/PageLoadIndicator"
+import { AdminBar } from "eddev"
+import { Header } from "@components/site/Header"
+import { defineView } from "eddev/views"
+import { fontFaceGlobalStyles, frontendGlobalStyles } from "@theme"
+import { Footer } from "@components/site/Footer"
+
+fontFaceGlobalStyles()
+frontendGlobalStyles()
+
+export default defineView("_app", ({ children }) => {
+  return (
+    <>
+      <PageLoadIndicator />
+      <AdminBar />
+      <Header />
+      {children}
+      <Footer />
+    </>
+  )
+})
+```
+
+## App Query
+
+You can write an `views/_app.graphql` file, and the result will be available on every page, via the `useAppData()` hook. The result _wont_ be passed in as props, so be sure to use the hook if you need to access it.
+
+Note that the `_app.graphql` query only runs _once_ — when the user first loads the page.
+
+This is especially useful for things like menus, which are often used on every page, and should be accessible from anywhere on the first render of the page.