Overview

eddev uses GraphQL as the data layer between WordPress and React. WPGraphQL exposes the schema, project .graphql files define exactly what data is public, and eddev generates TypeScript types and hooks from those files.

Most of the time, you write GraphQL files rather than fetch data manually.

File Locations

Location	What It Does
`views/_app.graphql`	Global app data, available through `_app.tsx` props and `useAppData()`
`views/*.graphql`	Data for the paired view, passed as view props before the route renders
`blocks/*/.graphql`	Data for the paired block, passed as block props
`queries/fragments/*/.graphql`	Reusable selections and generated fragment types
`queries/*/.graphql`	Runtime query and mutation hooks generated into `hooks/queries.ts`

Global Data

Fetch shared site shell data through views/_app.graphql.

View Data

Pair view templates with GraphQL files for route props.

Block Data

Select ACF and block fields before blocks render.

Fragments

Reuse GraphQL selections and generated fragment types.

Generated Files

The dev process generates:

types.graphql.ts - operation, fragment, enum, scalar, and schema-derived TypeScript types
types.views.ts - the ViewProps map used by defineView
types.blocks.ts - the BlockProps map used by defineBlock
types.util.ts - helper global types such as post types, page templates, block tags, and post meta types
hooks/queries.ts - runtime query and mutation hooks for files under queries/
schema.json - the local schema file used by editor tooling

These files are generated output. Do not edit them directly.

Automatic Versus Runtime Queries

View, Block, and Global Data queries are executed as part of rendering route data. They are available before the relevant view or block renders.

Runtime hooks from queries/*.graphql are different. They are browser-side runtime fetches, useful for search, filters, pagination, user-triggered data loading, and mutations. They are not part of the server-rendered route payload.

Query Hooks

Fetch runtime browser data through generated TanStack Query hooks.

Infinite Queries

Build load-more interfaces on WPGraphQL cursor connections.

Mutation Hooks

Call named runtime mutations through generated hooks.

Runtime Endpoints

Runtime hooks do not send arbitrary GraphQL text to the public /graphql endpoint. eddev exposes named REST endpoints instead:

GET /wp-json/ed/v1/query/{queryName}?params={...} for query hooks
POST /wp-json/ed/v1/mutation/{mutationName} for mutation hooks

The {queryName} or {mutationName} maps to a file under queries/. For example, queries/search/UseSearchResults.graphql is requested by name as search/UseSearchResults.

This keeps public runtime access limited to query files committed in the theme, while still using WPGraphQL internally.

Caching

View, app, and runtime query data use the cache settings from ed.config.json. Individual query files can override the cache duration with a leading comment:

# ttl: 300
query UseRecentPosts {
  posts(first: 3) {
    nodes {
      title
      uri
    }
  }
}

Use # nocache when a query should never be cached.