Core Philosophy

These principles are the foundation of every decision below. When in doubt, refer back to them.

• Co-location: Each component declares its own data requirements via a GraphQL fragment, right next to the rendering code. Data needs travel with the component, not separately.
• Data masking: A component can only access the fields it explicitly selected in its own fragment. Parents cannot see child fragment data, and vice versa. This prevents implicit coupling between components.
• Composition: Fragments compose into parent fragments and ultimately into queries, forming a tree that mirrors the component tree. The compiler flattens this into a single network request per query.
• Render-as-you-fetch: Start fetching data before the component that needs it renders. This avoids sequential request waterfalls.
• Normalized store: Relay maintains a flat, ID-keyed cache. When a mutation returns updated data, every component reading that data re-renders automatically. You do not need to manually propagate changes.

Compiler Workflow

Relay uses an ahead-of-time compiler that reads graphql tagged template literals in your code and generates runtime artifacts and TypeScript/Flow types.

Finding the config

The compiler looks for its config in these locations (checked in order):

• relay.config.{json,js,mjs,ts} in the project root
• A "relay" key in package.json

See <llm-docs>/getting-started/compiler-config.mdx for the full config schema. You can also emit a JSON Schema for the config by running npx relay-compiler config-json-schema.

Running the compiler

Run npx relay-compiler after any change to the contents of a graphql tagged template literal or the docblock of a Relay Resolver. Some projects add this as

…

mockdevice-testing

使用 MockDeviceKit 在无实体眼镜硬件时进行功能联调与测试验证

write-query

将自然语言数据需求转成高质量 SQL，并按方言优化复杂查询性能。