If I can't use headers with env variables in tsconfig.json, do I need to run the generate CLI command first?

[erosenberg]

I'm trying to get a better sense of if and when I need to run gql.tada generate schema --header 'Auth: $TOKEN' .....
Perfect world, I would be able to define everything necessary in my tsconfig.json, but I need to use env variables as header values, and those don't appear to work in .json files.

So, let's say I have a next.js application, and I'm spinning up my development server; when would I need to run gql.tada generate schema vs. when needing to run gql.tada generate output.

I have a start-server.sh file for local development. In my case, would I need to run them right after the other?

source .env

npx gql.tada generate schema $API_URL --header "Auth: $TOKEN"
npx gql.tada generate output

makes the most sense to me, but it appears to not be able to recognize the generated .schema file right after being run (maybe a race condition?). Is there one command I can run that takes care of both on startup?

I'm also using Docker, and am wondering if it sounds right to run gql.tada generate schema there, and then generate output in my start-server.sh script.

Edit: Created a related request for adding more examples like this one to the examples folder (#367)

[kitten]

So, let's say I have a next.js application, and I'm spinning up my development server; when would I need to run gql.tada generate schema vs. when needing to run gql.tada generate output.

That depends, but basically never.

You won't need to have either files present to start up a dev server. They're not runtime files, or generated runtime code, they're typings. So, neither will have to be present for your application to run.

The schema will have to be present so that an output file can be generated at all. This can happen as part of the TypeScript plugin though.

THe output file will hence be either generated by generate output or by the TypeScript plugin.

I don't really know why the above wouldn't work though, but it's worth checking whether you've got the right path set up for the schema file to be read.

[erosenberg]

Since I can't use the TypeScript plugin (because I'm relying on environment variables that are inaccessible in tsconfig.json), I would still have to run gql.tada generate schema and gql.tada generate output (since schema is required for output), right?
Am I wrong in thinking that if I can't configure the plugin correctly that I have to use the CLI commands? Or are they completely separate things?

[kitten]

In general, you'll need an SDL (i.e. schema) file, yes. If your schema is on a remote API, that does mean that you have to run gql.tada generate schema, if additional inputs are required for the API to deliver an introspection result successfully.

The output typings files are an entirely separate topic. Once you switch over your "schema" configuration option in your settings to then use the local file, you won't have to necessarily generate this file manually. You can generate this manually, which is useful when you have separate processes that rely on it
(Say, you don't commit it and are running tsc in your CI, or you commit it but want to check that it's up-to-date)

What I'd point out is, there's one exception here that can make this easier. If you, for example, are developing a GraphQL API locally, in the same monorepo, there's generally no need to use gql.tada generate schema, since you can modify your API to write the schema.graphql file automatically as you start up your dev server.

Some schema builders even have this built in, and it's generally really useful, since it gives you a fixed state of your schema that isn't reliant on making a remote API call.

[erosenberg]

Thanks for the explanation! This makes sense! In this case since I am working with a remote API, I'm going to run generate schema, generate output and then check in that order on start of the application.

[erosenberg]

@kitten - Out of curiosity, if I have to manually generate both my schema and output (instead of polling the server), what makes it different than just using codegen?

[kitten]

I mean, first of all just to repeat this 😅

you won't have to necessarily generate this file manually. You can generate this manually, which is useful when you have separate processes that rely on it
(Also see notes in the docs on this and re. committing this file: https://gql-tada.0no.co/get-started/workflows#generating-the-output-file)

Circling back to the schema file. You having to output it isn't something new and I'd consider fetching it from an API an anti-pattern. Unfortunately, going into the details in the docs is out of scope. But the important points are:

• No matter whether you use a code-first or SDL-first GraphQL schema builder, outputting the schema.graphql file and committing it, is always a good idea. That's pretty independently of gql.tada a good idea
• The CLI generate schema process still has to exist because not everyone is working in a monorepo
• Fetching it from URL is in the config for ease of use, but not generally expected to be a permanent solution
• We can't "undo" all the damage that's been done to the ecosystem that's causing front ends to sometimes use multiple GraphQL APIs at the same time, which defeats some of GraphQL's biggest strengths. But there's still good cases for it, so we support fetching schemas from URLs
• We can't load environment variables in a TypeScript plugin which runs in an isolated environment

So, backing up here, there's several reasons why loading the schema is relevant.

Now, how is having an output file different from codegen. The output file is valid for the part of the schema you're using indefinitely. That means, not re-generating it has no consequences. However, the TypeScript plugin still needs schema information to give you:

• auto-completions
• diagnostics
• type hints

Whether or not one considers this codegen (and gql.tada generate turbo leans more into this) is not really relevant to the Developer Experience ultimately.
Codegen tools, like GraphQL Code Generator, just don't behave well and don't lead to the developer experience that gql.tada has reached 😅 Even in watch mode, GraphQL Code Generator won't behave as well and seamlessly

The reason why "No Codegen" is a good tagline is because it builds up a mental image of what this means for the editing experience, because codegen comes with inherent drawbacks (from minor issues like watch mode not being able to pick up changes as you type all the way to runtime code leaking into your bundle)

So, if you'd ask me to explain gql.tada and why it exists to someone, saying "No Codegen" is basically the shortest way to get the idea across. However, it's not possible to conjure schema information out of nothing. TypeScript will have to be fed information from somewhere.

While gql.tada actually is able to accept raw introspection data, in general, the output typings file has changed a little to improve performance. (Although you can actually still switch to the old format)

The reason we support multiple formats is that, eventually — if someone is interested in building this, a schema builder could actually provide its introspection output as a type, which can be fed into gql.tada. This would effectively eliminate the output typings file entirely.

[erosenberg]

Thank you for explaining this! I 💯 understand now. I really appreciate the in-depth response and love this project!