How-to guide

Reach trains through your own documents

Applies from: Trax 1.67.0.

A host no longer generates a persisted document for each exposed train, and trax client no longer writes a trains/<train>.g.ts function for each one. A select-everything document grows with the number of paths through the answer, so a train answering EF entities that reference each other either stopped the host at HotChocolate's 2048-field limit or started and was refused for cost on every call. A frontend now writes the documents it sends, which the host already registers at boot (Fetch only what a component needs). Machine documents and the runProgress documents are unchanged.

Write a document for each train the frontend calls

For each generated function the frontend imports (startRun, ordersTabletCalls), add a .graphql file naming its operation the same way, Pascal case of the namespace and the field, so the function and its <Operation>Result type keep their names and no import changes:

# src/graphql/startRun.graphql
mutation StartRun($input: StartRunInput!) {
  dispatch {
    startRun(input: $input) {
      externalId
      output {
        runId
      }
    }
  }
}

Select what the page uses rather than the whole answer. To start from what the generated function sent, copy the train's documents[0].document out of the previous manifest.json before you export it again.

Register the documents on the host

Name the file trax client --documents writes in ClientDocuments(path), resolved against the content root, and make sure the host's build carries it:

using Trax.Api.GraphQL.Extensions;
using Trax.Api.GraphQL.PersistedOperations.Extensions;
 
builder.Services.AddTraxGraphQL(graphql =>
    graphql.UsePersistedOperations(opts =>
        opts.RequirePersisted(true)
            .SingleNode()
            .ClientDocuments(Path.Combine(AppContext.BaseDirectory, "trax.documents.json"))
    )
);

Export the manifest and regenerate the client

The manifest is now format 3: each train lists its arguments instead of a document. Export it again from the host and run trax client with --documents, from the frontend's folder, with the same arguments in CI's --check:

trax client --manifest src/trax/manifest.json --out src/trax --documents 'src/graphql/*.graphql'

• The trains/ folder goes. trax client deletes the trains/*.g.ts modules it wrote before, and writes documents/<operation>.g.ts in their place; index.g.ts exports the same names.
• An older trax client refuses the new manifest, naming both formats. Update the tool with the packages.

Deploy the host first

Deploy the host with its documents before the frontend. A page built before the deploy still sends a trax_train_ id: the host answers SERVER_OUTDATED while a node of the earlier version may still serve it, and CLIENT_OUTDATED once its row is collected, a grace period after no node registers it, so the page reloads into the new frontend. The trax_train_ prefix stays reserved, so nothing can be uploaded under it.