diff --git a/blog/tailcall-n+1-working-2024-08-04.md b/blog/tailcall-n+1-working-2024-08-04.md index 0ee97a12d4..f734b9e863 100644 --- a/blog/tailcall-n+1-working-2024-08-04.md +++ b/blog/tailcall-n+1-working-2024-08-04.md @@ -112,7 +112,7 @@ It's simple, expressive and doesn't expose the guts of how data will be queried, ## The Algorithm -Tailcall reads your [configuration](/docs/tailcall-graphql-configuration-format-conversion), parses it, and internally stores it in an efficient graph data-structure that resembles a `HashMap`. This allows `O(1)` access to a GraphQL type which represented as a node by its name. Once the graph data-structure is ready we make it go through a series of validators, one of them being the **N+1 tracker**. +Tailcall reads your configuration, parses it, and internally stores it in an efficient graph data-structure that resembles a `HashMap`. This allows `O(1)` access to a GraphQL type which represented as a node by its name. Once the graph data-structure is ready we make it go through a series of validators, one of them being the **N+1 tracker**. Now, here's where it gets fascinating. We use a Depth-First Search (DFS) algorithm, starting at the root query and traversing all the connected nodes. Let me walk you through this cool process: diff --git a/docs/apollo-federation-subgraph.md b/docs/apollo-federation-subgraph.md index bc7f0e099d..c56e32302d 100644 --- a/docs/apollo-federation-subgraph.md +++ b/docs/apollo-federation-subgraph.md @@ -19,7 +19,7 @@ Skip this step if you don't have entities for now or want to add them later. Now you need to add [entity resolvers](https://www.apollographql.com/docs/federation/entities/) to the Tailcall config to make it act as a subgraph. -To do this, you need to define resolver on types by using one of the [directives](./configuration.mdx) that resolve the data. Use [`{{.value}}`](https://tailcall.run/docs/graphql-resolver-context-tailcall/#value) to access the fields that act as a federation `@key` and will be provided by the Federation Router when making the request to this subgraph. +To do this, you need to define resolver on types by using one of the [directives](./directives.md) that resolve the data. Use [`{{.value}}`](https://tailcall.run/docs/graphql-resolver-context-tailcall/#value) to access the fields that act as a federation `@key` and will be provided by the Federation Router when making the request to this subgraph. ```graphql type Post diff --git a/docs/cli.md b/docs/cli.md index 3babd480c9..4b5dea5edc 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -53,14 +53,6 @@ The `check` command allows for files. Specify each file path, separated by a spa tailcall check --schema ./path/to/file1.graphql ./path/to/file2.graphql ``` -### --format - -This is an optional command which allows changing the format of the input file. It accepts `gql` or `graphql`,`yml` or `yaml`, `json` . - -```bash -tailcall check ./path/to/file1.graphql ./path/to/file2.graphql --format json -``` - ### --verify-ssl Controls SSL/TLS certificate verification when loading remote configuration files. @@ -119,13 +111,17 @@ tailcall init This command prompts for file creation and configuration, creating the following files: -| File Name | Description | -| ------------------------: | --------------------------------------------------------------------------------------------------------------------------------------- | -| [.tailcallrc.schema.json] | Provides autocomplete in your editor when the configuration is written in `json` or `yml` format. | -| [.graphqlrc.yml] | An IDE configuration that references your GraphQL configuration (if it's in `.graphql` format) and the following `.tailcallrc.graphql`. | -| [.tailcallrc.graphql] | Contains Tailcall specific auto-completions for `.graphql` format. | +| File Name | Description | +| --------: | ----------- | + + + + +| [.graphqlrc.yml] | An IDE configuration that references your GraphQL schema and the following `.tailcallrc.graphql`. | +| [.tailcallrc.graphql] | Contains Tailcall specific auto-completions for `.graphql` format. | + + -[.tailcallrc.schema.json]: https://github.com/tailcallhq/tailcall/blob/main/generated/.tailcallrc.schema.json [.graphqlrc.yml]: https://the-guild.dev/graphql/config/docs [.tailcallrc.graphql]: https://github.com/tailcallhq/tailcall/blob/main/generated/.tailcallrc.graphql @@ -187,8 +183,7 @@ To generate a Tailcall GraphQL configuration, provide a configuration file to th } ], "output": { - "path": "./output.graphql", - "format": "graphQL" + "path": "./output.graphql" }, "schema": { "query": "Query", @@ -236,7 +231,6 @@ inputs: url: "http://127.0.0.1:8080/rpc" output: path: "./output.graphql" - format: "graphQL" schema: query: "Query" mutation: "Mutation" @@ -404,14 +398,9 @@ The `inputs` section specifies the sources from which the GraphQL configuration ### Output -The `output` section specifies the path and format for the generated GraphQL configuration. +The `output` section specifies the path for the generated GraphQL configuration. - **path**: The file path where the output will be saved. -- **format**: The format of the output file. Supported formats are `json`, `yml`, and `graphQL`. - -:::tip -You can also change the format of the configuration later using the [check](#--format) command. -::: ### Preset diff --git a/docs/configuration.mdx b/docs/configuration.mdx deleted file mode 100644 index e82e8880e8..0000000000 --- a/docs/configuration.mdx +++ /dev/null @@ -1,356 +0,0 @@ ---- -title: GraphQL Configuration Formats -description: "Explore the format conversion capabilities of the Tailcall CLI, supporting GraphQL, YAML, and JSON for configuration files. This documentation shows developers how to effortlessly convert and manage configurations, leveraging GraphQL for clear type definitions, and YAML and JSON for their ubiquity in tools and API integration. Enhance your development and deployment workflows today." -slug: tailcall-graphql-configuration-format-conversion -sidebar_label: Configuration Formats ---- - -import Tabs from "@theme/Tabs" -import TabItem from "@theme/TabItem" - -The Tailcall CLI's [check](./cli.md#check) command enables the conversion of configuration files between three supported formats: gql or graphql, yml or yaml, and json, with `graphql` set as the default format. - -The three formats, `GraphQL`, `YAML`, and `JSON`, are supported due to their distinct advantages. `GraphQL` is chosen for its ability to clearly define types and their relationships. `YAML` and `JSON` are included for their widespread use in platform tools, with `JSON` also favored for its role as a transport format, allowing configurations to be auto generated and exposed as APIs for consumption by the GraphQL server. - -## Converting Formats - -To convert files between different formats, use the following command: - -```bash -tailcall check format_type < input_files > --format -``` - -Let's try to convert a Tailcall graphql file to json and then back to graphql - -To convert graphql to json - -```bash -tailcall check examples/jsonplaceholder.graphql --format json > "examples/jsonplaceholder.json" -``` - -Now to convert back to graphql - -```bash -tailcall check examples/jsonplaceholder.json --format graphql > "examples/jsonplaceholder2.graphql" -``` - -To learn more about writing configuration to leverage the full power of Tailcall, explore the [Directives](./directives.md) documentation. - -## Format Conversions - - - - -```graphql showLineNumbers -schema @server(port: 8000, hostname: "0.0.0.0") @upstream(httpCache: 42, batch: {delay: 100}) { - query: Query -} - -type Query { - posts: [Post] @http(url: "http://jsonplaceholder.typicode.com/posts") - users: [User] @http(url: "http://jsonplaceholder.typicode.com/users") - user(id: Int!): User @http(url: "http://jsonplaceholder.typicode.com/users/{{.args.id}}") -} - -type User { - id: Int! - name: String! - username: String! - email: String! - phone: String - website: String -} - -type Post { - id: Int! - userId: Int! - title: String! - body: String! - user: User @call(query: "user", args: {id: "{{.value.userId}}"}) -} -``` - - - -```yml showLineNumbers -server: - hostname: 0.0.0.0 - port: 8000 -upstream: - httpCache: 42 - batch: - maxSize: 100 - delay: 100 - headers: [] -schema: - query: Query -types: - Post: - fields: - body: - type: - name: String - required: true - cache: null - id: - type: - name: Int - required: true - cache: null - title: - type: - name: String - required: true - cache: null - user: - type: - name: User - cache: null - userId: - type: - name: Int - required: true - cache: null - cache: null - Query: - fields: - posts: - type: - list: - name: Post - http: - url: http://jsonplaceholder.typicode.com/posts - cache: null - user: - type: - name: User - args: - id: - type: - name: Int - required: true - http: - url: http://jsonplaceholder.typicode.com/users/{{.args.id}} - cache: null - users: - type: - list: - name: User - http: - url: http://jsonplaceholder.typicode.com/users - cache: null - cache: null - User: - fields: - email: - type: - name: String - required: true - cache: null - id: - type: - name: Int - required: true - cache: null - name: - type: - name: String - required: true - cache: null - phone: - type: - name: String - cache: null - username: - type: - name: String - required: true - cache: null - website: - type: - name: String - cache: null - cache: null -``` - - - -```json showLineNumbers -{ - "server": { - "hostname": "0.0.0.0", - "port": 8000 - }, - "upstream": { - "httpCache": 42, - "batch": { - "maxSize": 100, - "delay": 100, - "headers": [] - } - }, - "schema": { - "query": "Query" - }, - "types": { - "Post": { - "fields": { - "body": { - "type": { - "name": "String", - "required": true - }, - "cache": null - }, - "id": { - "type": { - "name": "Int", - "required": true - }, - "cache": null - }, - "title": { - "type": { - "name": "String", - "required": true - }, - "cache": null - }, - "user": { - "type": { - "name": "User" - }, - "cache": null - }, - "userId": { - "type": { - "name": "Int", - "required": true - }, - "cache": null - } - }, - "cache": null - }, - "Query": { - "fields": { - "posts": { - "type": { - "list": { - "name": "Post" - } - }, - "http": { - "url": "http://jsonplaceholder.typicode.com/posts" - }, - "cache": null - }, - "user": { - "type": { - "name": "User" - }, - "args": { - "id": { - "type": { - "name": "Int", - "required": true - } - } - }, - "http": { - "url": "http://jsonplaceholder.typicode.com/users/{{.args.id}}" - }, - "cache": null - }, - "users": { - "type": { - "list": { - "name": "User" - } - }, - "http": { - "url": "http://jsonplaceholder.typicode.com/users" - }, - "cache": null - } - }, - "cache": null - }, - "User": { - "fields": { - "email": { - "type": { - "name": "String", - "required": true - }, - "cache": null - }, - "id": { - "type": { - "name": "Int", - "required": true - }, - "cache": null - }, - "name": { - "type": { - "name": "String", - "required": true - }, - "cache": null - }, - "phone": { - "type": { - "name": "String" - }, - "cache": null - }, - "username": { - "type": { - "name": "String", - "required": true - }, - "cache": null - }, - "website": { - "type": { - "name": "String" - }, - "cache": null - } - }, - "cache": null - } - } -} -``` - - - -## Editor Support - -To leverage autocomplete and validation for GraphQL configurations, the [init](./cli.md#init) command can be used to automatically create `.tailcallrc.graphql` for GraphQL configurations and `.tailcallrc.schema.json` for JSON and YAML configurations. These files enhance editor support by providing schema definitions, facilitating faster and error-free configuration. - -### GraphQL - -When you run `tailcall init`, it creates a `.tailcallrc.graphql` file containing your GraphQL schema definitions and a `.graphqlrc.yml` file configured to use this schema. The `.graphqlrc.yml` file is set up as follows: - -```yml -schema: - - "./.tailcallrc.graphql" - - "./app.graphql" -``` - -This file contains the path to the `.tailcallrc.graphql` file and the path to the main GraphQL configuration file which is `app.graphql`. This setup allows GraphQL IDE plugins and Language Server Protocols (LSP) to automatically pick up the schema for autocomplete and validation, enhancing your development experience with real-time feedback and suggestions. - -### JSON & YAML - -For JSON or YAML configurations, `tailcall init` also creates a `.tailcallrc.schema.json` file. To enable validation and autocomplete in your JSON files, reference the `.tailcallrc.schema.json` in the `$schema` attribute at the beginning of your JSON file: - -```json -{ - "$schema": "./.tailcallrc.schema.json" -} -``` - -This reference enables your IDE to validate and autocomplete using the JSON schema, offering a streamlined configuration process with instant error and typo detection. diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx index 426ba53ace..82d9da2c98 100644 --- a/docs/getting-started.mdx +++ b/docs/getting-started.mdx @@ -123,22 +123,19 @@ tailcall init The command will ask you a few questions and based on your input bootstrap a new GraphQL project with a few files: -1. `.tailcallrc.schema.json`: Provides autocomplete in your editor when the configuration is written in `json` or `yml` format. -2. `.graphqlrc.yml`: An IDE configuration that references your GraphQL configuration (if it's in `.graphql` format) and the following `.tailcallrc.graphql`. -3. `.tailcallrc.graphql`: Contains Tailcall specific auto-completions for `.graphql` format. -4. `main.graphql`: This is your root configuration that contains +{/* TODO: uncomment when the Taillcall configuration will in separate file */} +{/* 1. `.tailcallrc.schema.json`: Provides autocomplete in your editor for the tailcall configuration written in `json` or `yml` format. */} + +1. `.graphqlrc.yml`: An IDE configuration that references your GraphQL schema and the following `.tailcallrc.graphql`. +2. `.tailcallrc.graphql`: Contains Tailcall specific auto-completions for `.graphql` format. +3. `main.graphql`: This is your root configuration that contains ## Writing a GraphQL Configuration For our first example, we are going to compose a GraphQL schema from the REST APIs at https://jsonplaceholder.typicode.com, a free online REST API with some fake data. We will use the API at `/users` to get a list of users, and `/users/:id/posts` to get the posts for each user, and compose them into a single GraphQL schema. -We can use the following formats to define our GraphQL schema: `.graphql`, `.yml`, `.json`. - -Create one of the following files and paste the contents into it. - - - +Create a new file and paste the contents into it. ```graphql showLineNumbers schema @@ -173,217 +170,16 @@ type Post { } ``` - - - -```yml showLineNumbers -server: - port: 8000 - queryValidation: false - hostname: "0.0.0.0" -upstream: - httpCache: 42 -schema: - query: Query -types: - Post: - fields: - body: - type: - name: String - required: true - id: - type: - name: Int - required: true - title: - type: - name: String - required: true - user: - type: - name: User - userId: - type: - name: Int - required: true - cache: null - Query: - fields: - posts: - type: - list: - name: Post - http: - url: http://jsonplaceholder.typicode.com/posts - User: - fields: - email: - type: - name: String - required: true - id: - type: - name: Int - required: true - name: - type: - name: String - required: true - phone: - type: - name: String - username: - type: - name: String - required: true - website: - type: - name: String -``` - - - - -```json showLineNumbers -{ - "server": { - "port": 8000, - "queryValidation": false, - "hostname": "0.0.0.0" - }, - "upstream": { - "httpCache": 42 - }, - "schema": { - "query": "Query" - }, - "types": { - "Post": { - "fields": { - "body": { - "type": { - "name": "String", - "required": true - } - }, - "id": { - "type": { - "name": "Int", - "required": true - } - }, - "title": { - "type": { - "name": "String", - "required": true - } - }, - "user": { - "type": { - "name": "User" - }, - "http": { - "url": "http://jsonplaceholder.typicode.com/users/{{.value.userId}}" - } - }, - "userId": { - "type": { - "name": "Int", - "required": true - } - } - } - }, - "Query": { - "fields": { - "posts": { - "type": { - "list": { - "name": "Post" - } - }, - "http": { - "url": "http://jsonplaceholder.typicode.com/posts" - } - } - } - }, - "User": { - "fields": { - "email": { - "type": { - "name": "String", - "required": true - } - }, - "id": { - "type": { - "name": "Int", - "required": true - } - }, - "name": { - "type": { - "name": "String", - "required": true - } - }, - "phone": { - "type": { - "name": "String" - } - }, - "username": { - "type": { - "name": "String", - "required": true - } - }, - "website": { - "type": { - "name": "String" - } - } - } - } - } -} -``` - - - - The above file is a standard `.graphQL` file, with some minor additions such as `@upstream` and `@http` directives. Basically we specify the GraphQL schema and how to resolve that GraphQL schema in the same file, without having to write any code! ## Starting the GraphQL server Now, run the following command to start the server with the full path to the file that you created earlier. - - - ```bash tailcall start ./jsonplaceholder.graphql ``` - - - -```bash -tailcall start ./jsonplaceholder.yml -``` - - - - -```bash -tailcall start ./jsonplaceholder.json -``` - - - - If the command succeeds, you should see logs like the following below. ```bash diff --git a/docs/tailcall-on-fly.md b/docs/tailcall-on-fly.md index b5fd267752..de24feb87e 100644 --- a/docs/tailcall-on-fly.md +++ b/docs/tailcall-on-fly.md @@ -61,10 +61,6 @@ In this example, we will deploy a simple GraphQL server using `tailcall` on Fly. Below is the configuration present in the template repository, which will be used for this deployment. -:::tip -You can learn more about the configuration [here](./configuration.mdx) -::: - ```graphql schema { query: Query diff --git a/sidebars.ts b/sidebars.ts index fab822e26a..78097bba92 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -62,7 +62,6 @@ const sidebars: SidebarsConfig = { "rest", "scalar", "environment-variables", - "configuration", "config-generation", "apollo-federation-subgraph", ],