DEV Community: noire.munich

How-to organize your cells for flexibility

noire.munich — Thu, 22 Jun 2023 09:36:18 +0000

One of the early defining feature of #redwoodJS was Cells: React components designed to help you organise a Graphql's request lifecycle with frontend components for each of its states. RWJS is rather flexible, which leaves a lot of freedom for creative design and spectacular mistakes (I've had my share). Organising your code can become a challenge, so this post is meant to help you.

Over my past 3 years full time on RWJS I have been repeatedly confronted to the feeling that Cells were useful but were difficult to scale with. At the end of the day, I feel like the only real immutable part of a Cell, thus defining its nature, being the QUERY, there was no reason to feel constrained by a Cell's other parts, namely:

{ QUERY, beforeQuery, afterQuery, isEmpty, Loading, Failure, Empty, Success, displayName, }

Most of the time the only thing I had to change was the Success component, which created the itch, but was not big enough to bring forward a clearer solution. I used as and variant props to change the Success component, but felt unsatisfied.

Better variants with createCell

The following proposition is far from being perfect, but it's the one version that allowed me to feel confident in a design based on RedwoodJS, with minor tweaks to take cells to another level. I admit I might have been the only one in need of this and that it may be for lack of better engineering skills, but hey, it's a journey, we're all learning.

createCell powers the transformation of your XCell.tsx. The framework exposes it, so you can reuse it and get creative.

To address my code organisation problem with a 'variant' solution, I'm fulling relying on createCell.

Step by step

Create variants

In the same directory as the cell you are working on, create a variants directory and add the following as a base for index.ts:

// ./variants/index.ts
import * as List from './List'
import * as Select from './Select'

export type Variants = 'list' | 'select'

export const variants = new Map<Variants, unknown>([
  ['list', List],
  ['select', Select],
])

This declares only two variants, let's keep things simple and light. The exported type Variants helps with the Cell's variant prop typing and variants is the map we will use in the default export.

Add the variant code

The imported modules, List and Select, should have at least one Cell part different from what we have defined in our original cell. In my case, I neutralized the Loading, Failure and Empty components in the Select variant and added a different afterQuery in the List variant.
I didn't do it, but a better way to handle the specificity and complexity here would be to rely on yarn rw g cell X to create the boilerplate code for each variant. You'd be set with tests & stories upfront.

Neutralize the import transformer

Back in the cell's directory, rename your XCell.tsx to drop the Cell suffix, otherwise you'll have import conflicts. This remains your entry point and should have all your default Cell parts.

Activate variants with default support

Your default export in this file should look like the following:

type Params = {
  random: string
}

export default React.memo(function ({ variant, ...props }: {
  variant: Variants
} & CellSuccessProps<MyQuery, Exact<Params>>) {
  return createCell<
    CellSuccessProps<MyQuery, MyQueryVariables>,
    MyQueryVariables
  >({
    QUERY,
    afterQuery,
    Loading,
    Failure,
    Empty,
    Success,
    ...(variant ? variants.get(variant) : {}),
  })(props)
})

That's about it.

Now the reason I prefer this over the Cell boilerplate is that the generated code helped me develop fast but on longer term I found myself more confused when facing other cases for my cells, as I didn't necessarily anticipate the need for a cell to be way more flexible. For a long time I thought only working on a different Success component was enough - and in some way it is, but enabling the entire module to be altered in variants is helping me pushing design and attention to details a lot further.
Another solution would be to generate the same cell with a different name and the same query over and over, but this rings to me as a trap to bloat the codebase and face more and more the dreaded problem of naming things.

So I'll stick to this variants implementation.

Lightsail to deploy your first RedwoodJS App

noire.munich — Mon, 31 Oct 2022 08:28:22 +0000

So you've been trying out RedwoodJS and are looking for some easy AWS hosting solution.

AWS Lightsail and RedwoodJS Baremetal have you covered.

For that we will assume you have your repo with your RedwoodJS app ready to be deployed.
This short tutorial should set you on the right path, however I have not yet covered the api side. Come back later, as I intend to explore this as well.

At the end of this tutorial you will get an instance of Lightsail up & running with the web side of your application's current version served to a public static IP and bound to your domain.

Let's get this thing started:

Sign in AWS

Go to Lightsail and create your first instance

Pick the Linux/Unix platform
Select the Apps + OS blueprint category
Tick the Node.js blueprint

Make sure your ssh key is configured properly as we are not going to cover that here. You can change this later though.

Select your instance plan, but be aware that you will need at least 1GB of RAM otherwise the deploy will fail to heap usage.

Name your instance and tag it if that's how you work.
Your instance is being created.

Create and assign a static IP

Go to the Lightsail > Networking tab and create a Static IP. Into the IP page, attach your newly created instance.
Copy the new IP, you will need it in a minute.
Disable IPv6 - this is not ideal but it will help you install a certificate later on with minimal effort.

Create a domain

If you don't have one, create a domain on AWS Route 53.
If you already have one, you will need to update the DNS of your domain provider to add the records.
Remove any IPv6 record from your domain's configuration that may be lingering - it would have to be an AAAA record.

Configure the DNS

Go to Route 53 > Hosted zones and select your domain.
Create a new Record of type 'A', leave its name empty and change its value to add the IP address you should still have in your clipboard - the static IP we created earlier in Lightsail.
Set the TTL at 60 if it is not already and save.

This solution doesn't feel ideal but getting it to work with Lightsail's DNS wasn't getting me anywhere. It is valid though and documented by AWS here

What happens next should happen in your instance, so please, SSH there now

Create a ssh key and add it to Github

In terminal use ssh-keygen - passphrase is optional but recommended.
In ~/.ssh use cat on the [your_keyname_file].pub (hence on the .pub) and add it to your Github settings. This will help your instance clone and update your app.

Manually add pm2

pm2 is necessary to deploy RedwoodJS baremetal and it is not included in the instance. That's going to be easy enough to fix, still in your ssh terminal:
sudo npm install pm2 -g

Create your certificate for HTTPS

You will use Bitnami's installed bncert tool, which will set you up with a Let's encrypt certificate in no time. The tool is preinstalled, so just run the following command. Make sure your domains are comma separated. We do not cover www.[domain] in this tutorial so you are on your own for that.

$ sudo /opt/bitnami/bncert-tool --domains [domain1,domain2,...]

And follow on the instructions. It will install a certificate thanks to https://letsencrypt.org/fr/, so it's free.

Update Apache hosts

Now we need to fix our Apache hosts to make sure they will serve your app.
In terminal, open the file and update the path of the app to add the suffix /current/web/dist :

$ vim /opt/bitnami/apache2/conf/bitnami/bitnami.conf

That's good. For port :80, HTTP protocol.
You should report the same modification in here to support HTTPS:

$ sudo vim /opt/bitnami/apache2/conf/bitnami/bitnami-ssl.conf

Save and restart apache:

$ sudo /opt/bitnami/ctlscript.sh restart apache

Please leave your instance now and go back to your local terminal, astutely positioned to your app's root directory. We should stay local as of now.

Setup the baremetal deploy for your RedwoodJS app

Enter the command:

yarn rw setup deploy baremetal

It should create you the following files:

deploy.toml
ecosystem.config.js
web/src/maintenance.html

Update `deploy.toml`

Mine looks roughly like this:

[[production.servers]]
host = "[static ip configured in Lightsail]"
username = "bitnami"
privateKeyPath = "[location to the default Lightsail SSH key file you would have configured while creating your Lightstail instance]"
agentForward = true
sides = ["api","web"]
packageManagerCommand = "yarn"
monitorCommand = "pm2"
path = "/home/bitnami/htdocs"
processNames = ["serve"]
repo = "[path to your git repo]"
branch = "main"
keepReleases = 5

That should do the trick. host, privateKeyPath, path and repo should be updated accordingly.

Change your redwood.toml to update the web port

Update redwood.toml:

[web]
  title = "Redwood App"
-  port = 8910
+  port = 80

Should be enough.

Now commit and push!

Run your first dpeloy

Back to terminal:

$ yarn rw deploy baremetal production --first-run

That's about it. Check your static IP, you should be good to go. If you just created your domain you're going to have to wait for a couple of days before you can check - AWS should notify you of its availability though and it can be way quicker.

Flex your cells

noire.munich — Thu, 17 Feb 2022 10:23:02 +0000

Some context

We've been building SportOffice on RedwoodJS for almost a year now and we've made a point to use the framework as it comes - with little to no exotic stuff sprayed over.

This helped us go live in December and today we are hitting numbers ( € ), with a CRM built entirely with RedwoodJS ( and, yeah, Stripe, AWS, we're in an ecosystem anyway ). RW's not in v1 yet, but there's no looking back for us.

Now with all its power in its standard setup, couple of things could need some exposition online to help people better understand what's possible with it.

Today, I will precisely talk about Cells.

Reminding you of Cells

In a standard Redwood app, you'd have a web and an api side, both self explanatory. The api would be powered by Redwood itself - but it could be anything else, really, from an Express served api to a stitched graphql schema and beyond ( sky's the limit to Redwoods ).

Cells are components that manage the whole fetch-some-data-display-in-front cycle, errors and empty payloads included. A typical Cell will at the very least be a module with no default export, exporting:

a const QUERY = gql[...]
a const Success: React.FC<SuccessProps> = [...]

Sample below.

It's clean and easy, I've been using them for so long I don't even know if it ever felt difficult. Certainly it felt great to leave fetch calls in React components behind.

So, cells in themselves are very convenient, but sometimes you need a bit more flexibility. What if you needed to call entirely different queries but the rest of the component should stay the same? It's doable with a standard cell, but not in a very clean way.

Some code

What I'm about to show you is not neat and shiny, it's unpolished code extracted to demonstrate the point - please forgive me if your eyes do bleed. This is the price of knowledge ( for some of us ).

We needed a Select for all our Users where roles.include('student'). This has been enough for about ten months:

import { userToOption } from 'src/components/Model/User'  
import { Input, Select } from 'src/ui'  

export const QUERY = gql`  
 query SELECT_STUDENT($where: WhereUserInput) {  
     options: students(where: $where) {  
         id  
         firstname
         lastname  
     }
}`  

export const Loading = () => (  
  <Input name={'student'} disabled pointer={'model:student.label'} />  
)  

export const Success: typeof Select = ({  
  name = 'students',  
  options,  
  ...selectProps  
}) => (  
  <Select  
    {...selectProps}  
    name={name}  
    pointer={'model:student.label'}  
    options={options?.map((student) => userToOption(student))}  
  />  
)

It uses a students service with a where parameter, it's safe for you to assume that this should fit straight into a prisma query.

Problem now is that we need the same Select, targeting the same role, but in different contexts that will actually require different db queries.

One way to do that could be to pass an argument to our graphql query and then, on the api side, switch over it to trigger different method calls.
Though it's a valid way to handle this in some cases, I wasn't too keen this time on doing so. I'd prefer to keep my methods and endpoints explicit and focused, which I found to be more scalable.

To do so I created 3 endpoints, each with their own api services & separate methods, to fetch my students in their different context. And to make sure this would be used properly in front, I relied on createCell ( formerly withCell), to select the query I'd need to call:

import { createCell } from '@redwoodjs/web'  
import { userToOption } from 'src/components/Model/User'  
import { Input, Select } from 'src/ui'  

interface CellProps {  
  sessionId?: number  
  courseId?: number  
}  

export const QUERY_ALL_STUDENTS = gql`  
 query QUERY_ALL_STUDENTS($where: WhereUserInput) {  
   options: students(where: $where) {  
     id  
     firstname
     lastname  
   }
}`  

export const QUERY_SESSION_STUDENTS = gql`  
 query QUERY_SESSION_STUDENTS($id: Int) {  
   options: getSessionStudents(id: $id) {  
     id  
     firstname
     lastname  
   }
}`  

export const QUERY_COURSE_STUDENTS = gql`  
 query QUERY_COURSE_STUDENTS($id: Int) {  
   options: getCourseStudents(id: $id) {
     id  
     firstname
     lastname  
   }
}`  

const Loading = () => (  
  <Input name={'student'} disabled pointer={'model:student.label'} />  
)  

const Success = ({ selectProps, name, options }) => {  
  return (  
    <Select  
      {...selectProps}  
      name={name}  
      pointer={'model:student.label'}  
      options={options?.map((student) => userToOption(student))}  
    />  
 )  
}  

export default function ({ sessionId, courseId }: CellProps) {  
  const { query, id } = React.useMemo(() => {  
    switch (true) {  
      case Boolean(sessionId && !courseId):  
        return { id: sessionId, query: QUERY_SESSION_STUDENTS }  
      case Boolean(!sessionId && courseId):  
        return { id: courseId, query: QUERY_COURSE_STUDENTS }  
      default:  
        return { query: QUERY_ALL_STUDENTS }  
    }  
  }, [sessionId, courseId])  

  return createCell({  
    QUERY: query,  
    displayName: 'StudentsSelect',  
    Loading,  
    Success,  
  })({ id })  
}

I think this is the cleanest way I've found so far to deal with this.

It let's me keep a very clean API - which I'm going to really need further on as this is an important part of our business, and it lets me avoid creating dozens of the same component with only one prop to differentiate them.

So at the end of the day, I feel like it's clean enough on the web and api sides of my lawn.

Cheers,

Notes

Notice how each query has their own name? Whichever way you want to tackle such issue, always keep in mind graphql client will require you to use query names as if they were ids. RedwoodJS will let some warning show if you don't comply.
Cells are documented here, here as well and here

Testing with react-i18next in RedwoodJS

noire.munich — Tue, 25 Jan 2022 16:15:35 +0000

This post assumes you've already fiddled with RedwoodJS and are looking further into it for something you'd show the world. It is about testing & translation, hence the title. If you have experience with both topics, the article might not be very relevant to you, instead I'd suggest checking out RedwoodJS.

Context

A while back as I was trying to set up my current project, I tried to follow the Redwood Way ( no definitive specification on that one as of yet, AFAIK ) and implement frontend tests. I had never worked with frontend tests before and soon enough I stumbled onto performance issues. The ticket doesn't show the real story, but what happened was that I had errors thrown and no way to gather enough information to understand what was going on - and having to wait 90 seconds for any file update quickly became an obstacle I couldn't deal with.

I left the frontend tests aside until @jtoar pinged me on the original issue this week. v0.42 ships with improvements on testing, I had to try it and see where we were at now.

To do so I met my following problem: tests were still failing, but in 10s, which is way better and let me investigate a bit more the core of my problem - translation.

Hands on

If your application supports translation, you may find yourself with many components relying on i18n 's ( or your library of choice to handle that ) functions or components. Those may impair your tests if you do not use proper mocks.
Fortunately this is rather straightforward. This example works with react-i18next.
First, let's define a component that will use the library. Let's KISS this:

import { useTranslation } from 'react-i18next'  

const Input = ({ pointer, name }) => {  
  const { t } = useTranslation()  

  return (  
    <div>  
 <label>{t(pointer)}</label>  
 <input name={name} />  
 </div>  
 )  
}  

export default Input

Second, we need to define a test configuration for the library:

# src/configuration/i18nForTests.ts
import i18n from 'i18next'  

i18n      
.init({  
    lng: 'en',  
    fallbackLng: 'en',  

    // have a common namespace used around the full app    
ns: ['site'],  
    defaultNS: 'site',  

    debug: false,  

    interpolation: {  
      escapeValue: false, // not needed for react!!    
},  

    resources: { fr: { site: {}  } },  
  })  

export default i18n

Finally, we can run some tests:

import 'src/configuration/i18nForTests'  
import { fireEvent, render, screen } from '@redwoodjs/testing'  
import Input from './Input'  

jest.mock('react-i18next', () => ({  
  // this mock makes sure any components using the translate hook can use it without a warning being shown  
 useTranslation: () => {  
    return {  
      t: (str) => str,  
      i18n: {  
        changeLanguage: () => new Promise(() => {}),  
      },  
    }  
  },  
}))  

describe('UI/Input', function () {  
  it('Renders successfully', function () {  
    render(<Input name={'someInput'} pointer={'site:input.text'} />)  

    expect(screen.getByRole('textbox')).toBeInstanceOf(HTMLInputElement)  
  })  
})

That should do the trick. 10s of success, now!

There's a debug prop in the configuration object for i18n, if set to true you'll get information about missing keys. I haven't played with that, but if I had time, that could be valuable.

Happy coding.

Notes

RedwoodJS let's you setup translation with an out of the box cli command:

yarn rw setup i18n

If you pickup RedwoodJS and don't have strong preferences on translation libs, there's a solution for you.

DEV Community: noire.munich

How-to organize your cells for flexibility

Better variants with createCell

Step by step

Create variants

Add the variant code

Neutralize the import transformer

Activate variants with default support

Lightsail to deploy your first RedwoodJS App

Sign in AWS

Go to Lightsail and create your first instance

Create and assign a static IP

Create a domain

Configure the DNS

Create a ssh key and add it to Github

Manually add pm2

Create your certificate for HTTPS

Update Apache hosts

Setup the baremetal deploy for your RedwoodJS app

Update deploy.toml

Change your redwood.toml to update the web port

Run your first dpeloy

Flex your cells

Some context

Reminding you of Cells

Some code

Testing with react-i18next in RedwoodJS

Context

Hands on

Notes

Update `deploy.toml`