Configure Applications

You've probably used wunderctl already to initialize a new WunderGraph project. If not, please follow the first steps guide to get your started.

Assuming your WunderGraph project is set-up correctly, you should fine one important file in front of you:

wundergraph.config.ts

Quickstart#

You might want to take a shortcut and directly look into the code and explore the concepts yourself. If that's you, just open the file wundergraph.config.json, it should be straight forward.

Overview#

WunderGraph is built around the concept that all configuration should be possible using code. This allows you to fully customize your WunderGraph applications to your needs as well as allowing you to store your configuration in a git repository.

The former gives you a lot of freedom, the latter allows you to integrate WunderGraph into your Continuous Deployment pipeline, allowing for a nice GitOps integration.

We chose typescript as the language for the WunderGraph sdk because of two reasons. First, it's very close to JavaScript, the most widely used scripting language. Second, because typescript has type definitions, it's actually quite easy to use because autocompletion and linting can be very helpful.

To configure a WunderGraph application, you have to follow three simple steps.

  1. introspect one or more APIs
  2. combine the APIs into an application
  3. call "configureWunderGraph" to generate the WunderGraph configuration (wundergraph.config.js) and the clients.

Introspect an API#

Let's explore the different options of introspecting APIs

GraphQL#

In case you have an existing service which implements the GraphQL specification, use the following approach:

import {introspect, IntrospectionPolicy} from "@wundergraph/sdk";
const graphQLAPI = introspect.graphql({
source: IntrospectionPolicy.Network,
url: "http://localhost:4000",
})

This code makes an introspection requests to the service and generates an API object from it.

GraphQL Federation#

import {introspect,IntrospectionPolicy} from "@wundergraph/sdk";
const federatedApi = introspect.federation({
source: IntrospectionPolicy.Network,
urls: [
"http://localhost:4001/graphql",
"http://localhost:4002/graphql",
"http://localhost:4003/graphql",
"http://localhost:4004/graphql",
]
})

This code assumes that the four services implement the GraphQL Federation specification. The WunderGraph sdk will introspect them with an introspection Query and combines them into a federated GraphQL API object.

OpenAPISpecification#

WunderGraph also supports REST APIs, which get translated to GraphQL automatically. Here's one possible way of adding an OpenAPI based API to WunderGraph:

import {introspect} from "@wundergraph/sdk";
const openAPI = introspect.openApi({
source: {
kind: "file",
filePath: "my_api_oas.json"
},
})

This code reads the OpenAPISpecification from the filesystem and translates it into an API object.

Build an Application#

Now that you have one or more APIs introspected you're ready to combine them into an Application:

import {Application} from "@wundergraph/sdk";
const myApplication = new Application({
name: "app",
apis: [
/*federatedApi,
openAPI,
graphQLAPI*/
],
});

Simply add your api(s) to the application to combine their schemas into one single application schema.

Configure WunderGraph#

You should now have a WunderGraph application object ready to use.

The final step is to turn this application into a WunderGraph configuration file.

wundergraph.config.json

wundergraph.config.json can be used by wunderctl to start a local dev environment.

import {configureWunderGraph,templates} from "@wundergraph/sdk";
configureWunderGraph({
applications: [myApplication],
code_generators: [
{
templates: [
// use all the typescript react templates to generate a client
...templates.typescript.react,
],
// create-react-app expects all code to be inside /src
path: "../src/generated",
}
]
});

First, provide your application(s) to the options object. Next, configure the code generators.

In this case, we're generating a typescript client for our application. Because some application frameworks restrict the directories from which you can import files, you're able to configure the output folder for the client templates.

Start your application#

Once you're happy with your configuration, you can start the sdk.

# inside .wundergraph
yarn develop # or npm run develop

This will run the sdk in watch mode. Whenever you make a change, the wundergraph.config.json will be re-generated.

Lastly, you have to run a local WunderGraph dev environment using the wundergraph.config.json

wunderctl up