Getting started with RedwoodJS

Setting up and configuring a full-stack application can be a pain in the neck. Imagine how easy it would be to develop a JAMstack app if you didn’t have to deal with SSG or headless CMS?

In this guide, I’ll introduce you to RedwoodJS, a full-stack JAMstack framework built on React, GraphQL, and Prisma, and demonstrate how to use some of its key features.

What is RedwoodJS?

Many prominent tools and frameworks aim to simplify the development workflow. Some of them come with predefined setup for webpack, Babel, etc., which makes the process cumbersome. Redwood is a framework that makes decisions for you under the hood.

According to the documentation, Redwood is “an opinionated, full-stack, serverless web application framework that will allow you to build and deploy JAMstack applications with ease.”

Redwood is a React-like frontend that’s statically delivered by CDN. It talks via GraphQL to your backend running on AWS Lambdas, and it’s deployable by a simple git push.

Features

Before we get started, let’s break down the key frontend and backend features we’ll highlight throughout this tutorial.

Frontend features

• Unique file structure and formatting
• Simple but powerful routing (all routes defined in one file) with dynamic (typed) parameters, constraints, and named route functions to generate correct URLs
• Cells — a declarative way to fetch data from the backend API
• Generators that use CLIs to generate pages, layouts, and cells
• Predefined helpers and conventions for form validation and error handling for both the client and server side

Backend features

• Boilerplateless GraphQL API construction
• Generators that produce SDL and services on the fly
• Easy CRUD, which makes a scaffolding generator for CRUD operations around a specific DB table
• Database migrations via Prisma 2

Deployment features

For deployment, RedwoodJS features first-class JAMstack-style deployment to Netlify.

Prerequisites

To get started with RedwoodJS, you need some basic knowledge of React, GraphQL, and Prisma. That said, you don’t need to be an expert to pick up the Redwood framework.

You also need to have either Node version 12 or higher or yarn version 1.22 or higher installed in your machine. Otherwise, you might encounter issues along the way.

Installation

Redwood uses yarn to scaffold your app.

#Run the command and specify your folder name
yarn create redwood-app ./redwoodapp

After successful installation, you’ll have a new directory, redwoodapp, containing several directories and files. Change to that directory by running:

cd redwoodapp

To start the development server, run:

yarn redwood dev

A browser should automatically pop up to http://localhost:8910 and you’ll see the Redwood welcome page.

File structure

Redwood’s file structure has two parts: the api folder and the web folder. These are commonly referred to as workspaces.

Here’s what Redwood’s file structure looks like:

Web workspace

The web workspace comprises all component- and static-related files.

The public folder contains all the static assets, such as favicon, README, etc.

src holds other subdirectories, including:

• components, which contains your usual React components along with other Redwood cells
• layouts, which contains reusable components that wrap your content and are shared across other pages in your application
• pages, which contains components and is optionally wrapped inside layouts
• Routes.js, which defines all the routes in your app

API workspace

Routing

Redwood Router is unique compared to React Router. It’s a combination of React Router, Reach Router, and its own router.

Redwood Router (RR) is designed to list all routes in a single file, eliminating the need for nesting routes (which is not the case with React).

To use Redwood Router, import the Router and Route components from the @redwoodjs/router package. Creating a Route in Redwood requires path, name, and page to be passed as props into the Route component.

<Route path="/contact" page={ContactPage} name="contact" />

• path specifies which URL path to match
• page specifies which component to render when the path is matched
• name calls the Route component from the Link component. For example:

const AboutPage = () =>

RR makes it possible to include parameters in your path prop.

<Route path="/user/{id}" page={UserPage} name="user" />

It has a cool hook called useParam that enables you to extract the parameters.

import { useParams } from '@redwoodjs/router'
const MainComponent= () => {
  const { id } = useParams()
  // ...
}

By default, JavaScript specifies parameters as strings. But with Redwood routing, it offers a suitable pattern to convert your parameters to any data type of your choice.

You can specify route parameter types right in the path props.

<Route path="/admin/{id:Int}" page={AdminPage} name="admin" />

By using :Int annotation on the code above, the Route parameter will only match digits by using regex (/\d+/) and then use Number() to convert the parameter into a number.

Code splitting

By default, RR (when used in a Redwood app) will code-split on every page, creating a separate, lazy-loaded webpack bundle for each. When navigating from page to page, RR waits until the new page module is loaded before rerendering, thus preventing the “white flash” effect.

Check out the Redwood Router documentation to learn more about this feature.

Fetching data with cells

Data fetching in Redwood is different from the traditional asynchronous convention. The frontend and backend process data independently from each other. Usually, the frontend loads first while it waits for the data. In most cases, a loading indicator or spinner shows that data is fetched.

Redwood uses a pattern that adopts a declarative approach for fetching data from the server side (GraphQL).  A cell is a higher-order component that provides a dynamic sequence whereby it retrieves data from an API showing a loading state using a placeholder and then displays the result as a reusable pattern.

The cell contains the GraphQL query and loading, empty, error, and success states, each one rendering itself automatically depending on the state of your cell. All you need to do is specify the query; Redwood does all the magic for you under the hood.

A typical cell file looks like this:

export const QUERY = gql`

  query {
    posts {
      id
      title
      body
    }
  }
`
export const Loading = () => <div>Loading...</div>

export const Empty = () => <div>No posts yet!</div>

export const Failure = ({ error }) => (
  <div>Error loading posts: {error.message}</div>
)

export const Success = ({ posts }) => {
  return posts.map((post) => (
    <article>
      <h2>{post.title}</h2>
      <div>{post.body}</div>
    </article>
  ))
}

To see a cell, you must import it into your page component.

import BlogLayout from 'src/layouts/BlogLayout'
import BlogPostsCell from 'src/components/BlogPostsCell'

const HomePage = () => {
  return (
    <BlogLayout>
      <BlogPostsCell />
    </BlogLayout>
  )
}

export default HomePage

In the code above, we imported a BlogPostCell and wrapped it inside the BlogLayout component.

Head to the Redwood cells documentation for more details.

Forms

Redwood forms have a lot of helper methods that make form handling and validations much easier to implement in web applications. It uses React Hook Form to make the form experience unique.

Command line generators

Redwood generates files using is own unique CLI inspired by Rails command line tools. This way, you can create any file inside the exact directory specified by you.

The Redwood CLI has one major entry point command, redwood (alias: rw), for developing an application.

You might use generate or g flag — either works fine.

The Redwood CLI tool automates repetitive tasks, such as generating files (pages, components, cells, etc.) and migrating the database, so you can work on what makes your application special.

Pros and cons of using RedwoodJS

Below are some reasons you might want to try Redwood in your next application.

• Redwood accommodates any full-stack application because it’s integrated with services, databases, and testing. It has a deployment paradigm that scales efficiently and requires almost no intervention. Plus, it uses the React frontend architecture and GraphQL, Prisma, and Apollo as its backend
• Redwood adopts the JAMstack approach to building web applications
• The tools and conventions in Redwood make building web applications a breeze compared to other frameworks. You can develop a CRUD application in Redwood in two minutes without any configuration

There also are a few bottlenecks to consider when using Redwood.

• Redwood is in its alpha stage, so it wouldn’t be advisable to develop a production-based app just yet. I believe the team is working hard to make a stable release soon
• There are limitations related to Lambda function length and issues with connecting serverless to relational databases

Predict COVID-19 is one of the first sites to use Redwood in production.

Conclusion

When RedwoodJS becomes stable, it’s not hard to see it evolving into a standard for building full-stack web applications. Developers will benefit from the continued performance and feature upgrades over time and with minimum effort.

Redwood makes your work easier by making logical decisions under the hood for you, enabling you to develop robust apps with less setup.

To learn more about Redwood, check out the following resources.

• Redwood documentation
• RedwoodJS video tutorial by Rob Cameron