Document multi-project config options

[kejistan]

There is some decent documentation for the single-project config options, but no mention of multi-project configs in any of the documentation. The test project uses a config in the multi-project format and the source for the format is pretty easy to read, but it'd be nice to have this documented in the same place as the single-project format.

[alunyov]

I think it is a good suggestion.

This section is something that should go into "Advanced Setup" or similar, as most of the projects do not need this config.

[sibelius]

when should one use multi-project config?

if I have a monorepo with many relay different project should I have a single relay config with all projects? or should I have many relay configs?

[alunyov]

@sibelius

I think for multi-config you'll need to have these two requirements:

1. You need to build all relay projects in the mono-repo with a single command
2. Every sub-project in the mono-repo have different schema/extensions/JS/TS language/persist config, etc

[mrtnzlml]

Example of a simple multi-config for anyone interested: https://github.com/adeira/universe/blob/master/relay.config.js (3 projects, 2 different schemas)

[orta]

As it can't hurt to have another working example, I switched to a monorepo and have this relay.config.json:

{
  "root": ".",
  "sources": {
    "apps/puzzmo.com": "app",
    "apps/studio": "studio"
  },
  "projects": {
    "app": {
      "language": "typescript",
      "output": "apps/puzzmo.com/src/__generated__",
      "schema": "api-schema.graphql",
      "eagerEsModules": true
    },
    "studio": {
      "language": "typescript",
      "output": "apps/studio/src/__generated__",
      "schema": "api-schema.graphql",
      "eagerEsModules": true
    }
  }
}

[ArturGraefenstein]

Another Example if you want to use a shared package with relay fragments which are consumed in multiple projects.

relay-base.config.js

module.exports = {
	schema: "schema.graphql",
	language: "typescript",
	customScalarTypes: {
		ZonedDateTIme: "string",
		BigDecimal: "number",
		DayOfWeek: "string",
		LocalTime: "string",
		LocalDate: "string",
	},
	noFutureProofEnums: true,
	eagerEsModules: true,
};

relay.config.js

const baseConfig = require("./relay-base.config.js");

module.exports = {
  root: ".",
  sources: {
    "apps/foo": "foo",
    "apps/bar": "bar",
    "packages/shared": "shared"
  },
  projects: {
    foo: {
      ...baseConfig,
      output: "./apps/foo/__generated__",
      base:  "shared",
    },
    bar: {
      ...baseConfig,
      output: "./apps/bar/__generated__",
      base: "shared"
    },
    shared: {
      ...baseConfig,
      output: "./packages/shared/__generated__",
    }
  }
};

This config works with the VSCode extension and the relay-compiler. You can use fragments from shared package in foo and in bar but you can not import fragments in foo from bar or vice-versa. This took me a long time to figure out and I wish it would be documented somewhere. I found it by looking into the sourcecode, but even there the base key is described in the comments as "inherit config from base project". But what it actually does is, it lets you use fragments from the base project in your referenced project.

I wish the relay-config would be better documented.

[ZachMayry]

When I try to this, I get this error:

[INFO] Querying files to compile...
[INFO] [foo] compiling...
thread '<unnamed>' panicked at 'no entry found for key', crates/relay-compiler/src/build_project/build_schema.rs:120:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Single config files with basically the same content are perfectly fine. I've tried multiple versions of relay from 15-20 I've tried multiple version of typescript from 5.2.0-5.9.2

Edit: I fixed it! Looks like there was a problem with an eslint package that yarn workspaces was able to just figure out and work fine, but somehow caused an issue with relay. Weird and confusing but trying to install node_modules with npm lead me to the error

[ZachMayry]

I was under the impression that setting a base would allow me to use fragments from shared within foo But when I try to use them and compile it, I get this:

yarn relay
[INFO] Querying files to compile...
[INFO] [shared] compiling...
[INFO] [foo] compiling...

thread '<unnamed>' panicked at crates/relay-typegen/src/write.rs:630:29:
Expected location for fragment useMyQuery_fragment.
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
[INFO] [shared] compiled documents: 2 reader, 1 normalization, 2 operation text

thread '<unnamed>' panicked at crates/relay-typegen/src/write.rs:630:29:
Expected location for fragment useMyQuery_fragment.
[ERROR] A thread that the Relay compiler spun up did not shut down gracefully: task 13 panicked with message "Expected location for fragment useMyQuery_fragment."
[ERROR] Compilation failed.
[ERROR] Unable to run relay compiler. Error details: 
A thread that the Relay compiler spun up did not shut down gracefully: task 13 panicked with message "Expected location for fragment useMyQuery_fragment."

Edit: Fixed again! Looks like you need to set the output folder to the root of the shared workspace for it to work

[captbaritone]

If the Relay compiler panics, that is a bug. Don’t have a minimal repro of a project that causes the compiler to panic like that which you can share?

Jordan Eldredge

jordaneldredge.com

On Sat, Sep 13, 2025 at 2:42 AM Zach @.***> wrote:

ZachMayry left a comment (facebook/relay#3795) https://github.com/facebook/relay/issues/3795#issuecomment-3287270663

I was under the impression that setting a base would allow me to use fragments from shared within foo But when I try to use them and compile it, I get this:

yarn relay [INFO] Querying files to compile... [INFO] [shared] compiling... [INFO] [foo] compiling...

thread '' panicked at crates/relay-typegen/src/write.rs:630:29: Expected location for fragment useMyQuery_fragment. note: run with RUST_BACKTRACE=1 environment variable to display a backtrace [INFO] [shared] compiled documents: 2 reader, 1 normalization, 2 operation text

thread '' panicked at crates/relay-typegen/src/write.rs:630:29: Expected location for fragment useMyQuery_fragment. [ERROR] A thread that the Relay compiler spun up did not shut down gracefully: task 13 panicked with message "Expected location for fragment useMyQuery_fragment." [ERROR] Compilation failed. [ERROR] Unable to run relay compiler. Error details: A thread that the Relay compiler spun up did not shut down gracefully: task 13 panicked with message "Expected location for fragment useMyQuery_fragment."

— Reply to this email directly, view it on GitHub https://github.com/facebook/relay/issues/3795#issuecomment-3287270663, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABHXL4XOKD37CTACCFYFXD3SNR6NAVCNFSM6AAAAAB2YTTE72VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTEOBXGI3TANRWGM . You are receiving this because you are subscribed to this thread.Message ID: @.***>