Your first WunderGraph Application

This is a guide to help you get started with WunderGraph and explore its capabilities. It will take <10 minutes to complete. Other guides will be more extensive and will cover more advanced topics.

In this example, we will create a simple WunderGraph application that shows the Weather for the capital cities of the world.

Let's get started!

Set up your project#

Install wunderctl#

Install wunderctl, the WunderGraph command line tool.

npm i -g @wundergraph/wunderctl@latest

Login to WunderHub#

In order to fetch APIs from WunderHub, you need to login. WunderHub is a service that provides a central repository of WunderGraph APIs, it's 100% free of charge for individuals.

wunderctl login

Once the login is complete, you're ready to start using WunderGraph.

Initialize your WunderGraph project#

Create an empty directory and cd into it, then run the following command.

wunderctl init
npm install

Add two API dependencies#

To be able to show the weather for the capital cities of the world, you need to add two API dependencies, a weather API and a country API.

Run the following command to accomplish this:

wunderctl add wundergraph/weather wundergraph/countries

You can also explore all available APIs on the WunderHub.

Configure the API dependencies#

You will see that the two API dependencies have been added to the wundergraph.manifest.json file. We now have to configure them.

Open the file wundergraph.config.ts to adjust the configuration.

import {integrations} from "./generated/wundergraph.integrations";

const weather = integrations.wundergraph.weather({
    apiNamespace: "weather",
});

const countries = integrations.wundergraph.countries({
    apiNamespace: "countries",
});

const myApplication = new Application({
    name: "app",
    apis: [
        weather,
        countries,
    ],
});

In our example, we instantiate both the weather and countries APIs, add a namespace for each one, and add them to our application.

Once you're done with this step, you can generate the GraphQL schema for your application using the following command:

wunderctl generate

This step composes the GraphQL schema from the API dependencies and applies the namespaces. We generate a GraphQL Schema file in the ./generated directory so that your IDE can use it to power intellisense and code completion.

Defining the Operation#

Now that our GraphQL schema is generated, we can define our first operation. Create a new file ./operations/Weather.graphql and add the following code:

query ($code: ID! $capital: String! @internal) {
    country: countries_country(code: $code){
        code
        name
        capital @export(as: "capital")
        weather: _join @transform(get: "weather_getCityByName.weather") {
            weather_getCityByName(name: $capital){
                weather {
                    summary {
                        title
                        description
                    }
                    temperature {
                        actual
                    }
                }
            }
        }
    }
}

This Operation takes a $code parameter and will fetch the weather for the capital of the country.

You can see multiple powerful WunderGraph concepts in action, but for now, let's focus on the basics.

If you're interested in the _join field, the @export, @internal and @transform directives, you can read more about them in the following docs.

• the _join field reference
• @export directive reference
• @internal directive reference
• @transform directive reference

Running our Application#

We've built our first WunderGraph application. All that's left is to run it and call our endpoint.

First, let's start our local environment:

wunderctl up --debug

Then, we're ready to call our endpoint:

curl http://localhost:9991/api/main/operations/Weather?code=DE

You can also open this URL in your browser to see the result. Try modifying the country code, e.g. US or GB.

If you look into the ./generated directory, you'll also see a Postman Collection generated for your API. You can import it into Postman to try out the API as well.

Conclusion#

That's it for this short guide. We've showed you how to import two APIs from the WunderHub, join them together, and create our first Endpoint.

You could now take it further and create more endpoints, generate a TypeScript or React Client on top, add Authentication, Caching, and more.

In the next section, we'll manually add more APIs to our application.