StepZen Netlify Build Plugin

We’re thrilled to announce that, with a new Netlify build plugin, you can now easily deploy a GraphQL endpoint built on StepZen with your Netlify build. With this, you can keep your APIs and your website consistent, and test and release them together using your existing deployment and testing processes. You can find the StepZen build plugin in the Netlify Plugin Catalog.

Netlify Plugin

Plugin: StepZen
Deploy a unified GraphQL endpoint in your Netlify Builds via StepZen

You are building your Jamstack sites and apps to serve up static and dynamic data using any number of APIs and data from myriad backends. However, APIs and backends have different authorizations, response protocols, syntax, and more. StepZen enables you to build a GraphQL API that is an API of APIs - different backends and ways of connecting to them are made uniform in the context of your GraphQL API. The unified API is easy to set up. You don't need to be a GraphQL expert, build a GraphQL server, or understand resolvers. You connect your API and database backends through configuration, not code. And, with a single query, you can ask for exactly the data you need to power your web experiences.

The StepZen plugin lets you easily integrate the deployment of the API in a Netlify build. No change is needed to the Netlify deployment process. Your GraphQL API runs on StepZen, as a service, so that you don't build or manage any infrastructure.

Setting up the StepZen plugin

Pre-requisites

  • You have a Netlify account and site
  • You have a StepZen account, and you know the account name and API Key
  • You have installed the StepZen CLI tool npm install -g stepzen (optional, recommended )
  • You have built a GraphQL API using StepZen. See Quickstart in StepZen docs. (optional, recommended)

Install the plugin into your Netlify site

The plugin is available in the Netlify Build Plugin directory. It is named netlify-plugin-stepzen on NPM and is hosted at https://github.com/steprz/netlify-plugin-stepzen

Search for StepZen in the Build Plugin directory, and click install or install it using the Netlify configuration file, which allows for more customization. Follow the instructions here.

Configure the plugin

  1. Create a stepzen directory containing your API specification. If you have built an API using StepZen, you can just copy the directory into your Netlify project root folder and name it stepzen.

  2. Add three environment variables, as specified here:

    • STEPZEN_ACCOUNT specifies the name of your StepZen account;
    • STEPZEN_ADMIN_KEY specifies the admin API Key that enables access to that account's endpoint.
    • STEPZEN_NAME specifies a name that StepZen uses for the resources related to this project.

  3. Optionally, you can specify two other environment variables.

    • STEPZEN_FOLDER is a folder within StepZen for project resources (this defaults to netlify)

    • STEPZEN_CONFIGURATION_SETS is a list of StepZen configuration sets to apply to your schema definitions. This is specified as a comma-separated string and defaults to netlify/configuration,stepzen/defaults.

      If you do not specify STEPZEN_CONFIGURATION_SETS, remember to name the configuration set you upload to StepZen as netlify/configuration. If you use more than one configuration set with your API, you must specify this environment variable.

  4. It's done!

How it works

  1. When you push changes to the main branch on GitHub (for cases where the source is stored in GitHub), GitHub calls a Netlify hook. (It works the same way if your source materials are in GitLab, or Bitbucket.)

  2. The hook triggers a checkout, build, and push on Netlify and results in the updated website served by the Netlify CDN.

    1. The build first establishes the build environment specified in the netlify.toml file, but before triggering the build process, it triggers the StepZen plugin.
    2. The build plugin compiles and pushes the contents of the GraphQL schema files (SDLs), which are contained in the stepzen directory, to the corresponding StepZen account.
    3. The site build process begins. Because the site build process is triggered after the StepZen plugin, StepZen APIs are available during the static build.
    4. Netlify completes the build and pushes the site to the Netlify CDN. Once the push completes successfully, the StepZen endpoint includes the updated GraphQL schema (SDL) code and is serving the new API.

This StepZen-Netlify integration simplifies your deployment. The workflow you use to deploy changes on Netlify does not change. You manage your GraphQL schemas (SDLs) in a cohesive way with the rest of the Netlify site and your releases are coordinated.

At runtime, StepZen ensures that API keys and queries are protected when making calls from a browser to retrieve and render data on the client-side. You don't need to write code to parallelize execution, store keys safely, handle caching, and more.

Where to go from here?

Have a number of APIs and backends powering your Jamstack site? Deploying your site on Netlify? Simplify aggregating the data from backend data sources by building a unified GraphQL API on StepZen and give the build plugin a try.

We’re honored to be featured as the Netlify Plugin of the Week. Thank you, Jessica, and the entire Netlify team for an awesome collaboration!