Redwood v7.0.0 is now available!

Announcements Releases and Upgrade Guides
1

Today we’re announcing Redwood v7.0.0! :rocket: The highlights of this major are Redwood Studio, many new and long-awaited GraphQL features like Realtime, Fragments, and Trusted Documents, the server file, new router hooks, upgrades to core dependencies like Prisma and so much more!

v7.0.0 Highlights

Redwood Studio

Redwood Studio is an observability tool that combines:

  • Tracing with OpenTelemetry (services and GraphQL)
  • SQL statement logging
  • general metrics (how many invocations)
  • GraphiQL playground with impersonated authentication

With Studio, it is easier to:

  • identify slow running SQL statements without reviewing captured log files
  • identify and improve N+1 queries by comparing before and after traces
  • impersonate the user authentication headers in GraphiQL

Redwood Studio is a command line tool which offers a web UI aimed at providing insights into your application via OpenTelemetry ingestion and other development conveniences like auth-impersonation within GraphiQL.

There’s no setup needed to begin using Studio; simply execute the following command to start Studio at localhost:4318:

yarn rw studio

The first time you run this command it will likely install the @redwoodjs/studio package which may take a small amount of time.

OpenTelemetry

If you want Studio to pick up telemetry from you app automatically please ensure you’ve setup OpenTelemetry. A guide on this can be found here:

Mailer

Redwood Studio is also tightly integrated with the mailer. Not only do you have the ability to send mail, but also the development tools you need to make the experience easier and more enjoyable.

You have a preview of what your mail templates will look like. These will re-render live as you update the template code.

There’s also a local inbox for previewing emails sent during development mode. This allows you to send full emails without worrying about setting up a local inbox or using an online temporary inbox service.

Additional information for working with the Mailer can be found within the docs.

GraphQL Realtime

One of the most often-asked questions before and after Redwood’s v1 launch was, “When will RedwoodJS support realtime?” In this release, serverful deploys can choose from two GraphQL Realtime solutions: Subscriptions and Live Queries. Additional information for GraphQL Realtime can be found in the docs.

GraphQL Fragments

GraphQL fragments are reusable units of GraphQL queries that allow you to define a set of fields that can be included in multiple queries. Fragments help improve code organization, reduce duplication, and make GraphQL queries more maintainable. They are particularly useful when you want to request the same set of fields on different parts of your data model or when you want to share query structures across multiple components or pages in your application.

To get started, run the following command:

yarn rw setup graphql fragments

registerFragment

To register a fragment, you can simply register it with registerFragment.

import { registerFragment } from '@redwoodjs/web/apollo'

registerFragment(
  gql`
    fragment BookInfo on Book {
      id
      title
      author
      publicationYear
    }
  `
)

This makes the BookInfo available to use in your query:

import type { GetBookDetails } from 'types/graphql'

import { useQuery } from '@redwoodjs/web'

import BookInfo from 'src/components/BookInfo'

const GET_BOOK_DETAILS = gql`
  query GetBookDetails($bookId: ID!) {
    book(id: $bookId) {
      ...BookInfo
      description
      # Include other fields specific to this query
    }
  }

// ...

const { data, loading} = useQuery<GetBookDetails>(GET_BOOK_DETAILS)

You can then access the book info from data and render:

{!loading  && (
  <div key={`book-id-${id}`}>
    <h3>Title: {data.title}</h3>
    <p>by {data.author} ({data.publicationYear})<>
  </div>
)}

You can find additional information about how Fragments work within the docs.

GraphQL Trusted Documents

Redwood can be set up to enforce persisted operations, alternatively called Trusted Documents. Use trusted documents if your GraphQL API is only for your own app (which is the case for most GraphQL APIs) for a massively decreased attack-surface, increased performance, and decreased bandwidth usage.

At app build time, Redwood extracts your app’s GraphQL documents (queries, etc) and make them available to the server. At run time, you can then send the “document id” or “hash” instead of the whole document—the server will only accept requests with a known document id. This prevents malicious attackers from executing arbitrary GraphQL thus helping with unwanted resolver traversal or information leaking.

Configuring Trusted Documents

Configuring is as simple as running the following command:

yarn redwood setup graphql trusted-documents

You can find additional information about how Trusted Documents work and manual setup within the docs.

Server File

Redwood v7 introduces a new entry point to Redwood’s api server: the server file at api/src/server.ts The server file was made with Docker in mind. It allows you to:

  1. have control over how the API server starts
  2. customize the server as much as you want, and
  3. minimize the number of dependencies needed to start the api server process (all you need is Node.js!)

Get started by running the setup command:

yarn rw setup server-file

This should give you a new file at api/src/server.ts.

Now, you can configure how the underlying Fastify server is instantiated and register Fastify plugins on the server instance.

Additional information can be found within the docs.

describeScenario

Typically, during the run of any single test, there is only one scenario’s worth of data present in the database. For example: users.standard or users.incomplete. The scenario sets up the database before each scenario test, runs the test, and then tears down (deletes) the scenario. This ensures that all tests are isolated, and they do not affect each other.

This should be the starting point for setting up tests that depend on the database. But there are some situations where you may want additional control around the timing of when the database is setup and torn down. describeScenario gives you that control:

describeScenario<StandardScenario>('contacts', (getScenario) => {
  // You can imagine the scenario setup happens here

  // All these tests now use the same setup 👇
  it('...', () => {
    // The scenario has to be retrieved using the getter
    const scenario = getScenario()
    // ...
  })

  it('...', () => {
    const scenario = getScenario()
    //...
  })
})

:construction_worker_man: Heads Up

Using describeScenario, your tests are no longer isolated. The results, or side effects, of prior tests can affect later tests.

The rationale for using describeScenario includes:

  • Create multi-step tests where the next test is dependent upon the results of the previous test.
  • Reduce testing run time. There is an overhead to setting up and tearing down the database on each test, and in some cases a reduced testing run time may have a significant benefit.

Additional examples can be found within the documentation.

New Router Hooks

This release comes with three new router hooks for better router introspection capabilities. Use these hooks to build more dynamic navigation components for your Redwood apps.

useRoutePaths() is a React hook you can use to get a map of all routes mapped to their literal paths, as they’re defined in your routes file. Example output:

{
  "editContact": "/contacts/{id:Int}/edit",
  "contact": "/contacts/{id:Int}",
  // ...
}

useRoutePath() (note the lack of an “s”) is a convenience hook for when you only want the path for a single route. If you don’t pass it any parameters it’ll get the path for the current route, otherwise it’ll give you the path for the route whose name you pass as the parameter. Example: useRoutePath('editContact') will return /contacts/{id:Int}/edit.

useRouteName() is used to get the name of the current route. So, for example, if the user is visiting /contacts/5/edit useRouteName() would return editContact.

You can read more about all three hooks in the Router docs.

Sentry

In this release you can set up Sentry error and performance monitoring across your Redwood app. From the command line, run:

yarn redwood setup monitoring sentry

This command installs and sets up @sentry/node and @sentry/react, enabling Prisma and Browser tracing to capture 100% of events.

The docs cover ways to further integrate:

  • Sentry Envelop Plugin
  • Setting up the Current User
  • Capturing Exceptions

Support for Prisma Bytes and GraphQL Scalar Byte

It’s now possible to use the Prisma Bytes data type (see the Prisma Schema reference). It’s typically used for object storage (think small thumbnail images or avatars).

Upgrade Guide

Changelog

11 Likes