✍️Coding Patterns

Coding patterns we follow on our front end

API

We're using Redux Toolkit Query (RTK Query) to define our API endpoints and cache the response data.

Defining Models

For each model defined on the back end, create a file named after the model in the directory api. At the top of the file, define the model on a global level and export it. Use the Model type constructor.

api/person.ts

import { type Model } from "codeforlife/utils/api"

export type Person = Model<
    number, // the type of the "id" field
    {
        first_name: string
        last_name: string
        age: number
    }
>

In addition, the name of each model will need to be registered as a tag in tagTypes, at api/index.ts.

api/index.ts

const api = createApi({
    tagTypes: ["Person"],
})

Picking Model Fields

If you'd like to define an object containing a subset of a model's fields, you can use Pick.

const person: Pick<Person, "id" | "age"> = { id: 1, age: 29 }

Defining Results & Args

When defining the result (i.e. response body) and arg (i.e. request body) for an endpoint, you must define their types as a pair on a global level below the model's type and export them. The result's type should come first, immediately followed by the arg's type. The result & arg types should follow the naming convention {endpoint_name}Result and {endpoint_name}Arg. Each result & arg pair should be separated with one newline.

api/person.ts

export type Person = Model<...>

// For endpoint "updatePersonName"
export type UpdatePersonNameResult = { id: number }
export type UpdatePersonNameArg = {
    id: number
    first_name: string
    last_name: string
}

// For endpoint "updatePersonAge"
export type UpdatePersonAgeResult = { id: number }
export type UpdatePersonAgeArg = {
    id: number
    age: number
}

If the fields of the result or arg are fields of the model, use the Result and Arg type constructors. These function similarly to Pick.

import { type Arg, type Result } from "codeforlife/utils/api"

export type UpdatePersonNameResult = Result<Person>
export type UpdatePersonNameArg = Arg<
  Person, // model
  never, // required fields.
  "first_name" | "last_name" // optional fields
> & Pick<Person, "id"> // "id" cannot be a required or optional field

If the result and arg are for a default action on the model-view-set, use the default type helper for the specific action. These function similarly to Pick.

import { type UpdateArg, type UpdateResult } from "codeforlife/utils/api"

export type UpdatePersonResult = UpdateResult<Person>
export type UpdatePersonArg = UpdateArg<
  Person, // model
  never, // required fields
  "first_name" | "last_name" | "age" // optional fields
> // "id" is picked by default

If no data is included in the result or arg, set either to null.

export type DeletePersonResult = null
export type DeletePersonArg = Person["id"]

Defining URLs

Documentation coming soon

Defining Endpoints

Endpoints should be defined below the result & arg pairs. Endpoints should be injected into the base API, imported from api/index.ts. The subset of API endpoints should follow the naming convention {model_name}Api and be exported as default. In addition, each hook auto-generated from the endpoints should be unpacked and exported as a constant below the default export.

api/person.ts

import api from "."

export type Person = Model<...>

export type UpdatePersonResult = UpdateResult<Person>
export type UpdatePersonArg = UpdateArg<Person, ...>

const personApi = api.injectEndpoints({
    endpoints: build => ({
        updatePerson: build.mutation<UpdatePersonResult, UpdatePersonArg>({
            query: ({ id, ...body }) => ({
                url: `persons/${id}/`,
                method: "PATCH",
                body,
            })
        })
    })
})

export default personApi
export const { useUpdatePersonMutation } = personApi

Defining a Retrieve Endpoint

When defining a retrieve endpoint, it's recommended to use the RetrieveResult and RetrieveArg type constructors. The endpoint should follow the naming convention retrieve{model_name}, be defined as a query, use the method "GET", and name the query's arg as id. To build the URL, the buildUrl utility should be called, providing the model's detail URL and id as a URL parameter. The tag should be provided by calling the tagData utility and providing the model's name as an argument.

import {
    type RetrieveArg,
    type RetrieveResult,
    buildUrl,
    tagData,
} from "codeforlife/utils/api"

export type RetrievePersonResult = RetrieveResult<Person, ...>
export type RetrievePersonArg = RetrieveArg<Person>

const personApi = api.injectEndpoints({
    endpoints: build => ({
        retrievePerson: build.query<RetrievePersonResult, RetrievePersonArg>({
            query: id => ({
                url: buildUrl(personUrls.detail, { url: { id } }),
                method: "GET",
            }),
            providesTags: tagData("Person")
        })
    })
})

Defining a List Endpoint

When defining a list endpoint, it's recommended to use the ListResult and ListArg type constructors. The endpoint should follow the naming convention list{model_name_plural}, be defined as a query, use the method "GET", and name the query's arg as search. To build the URL, the buildUrl utility should be called, providing the model's list URL and the search parameters. The tags should be provided by calling the tagData utility and providing the model's name as an argument and setting includeListTag to true.

import {
    type ListArg,
    type ListResult,
    buildUrl,
    tagData,
} from "codeforlife/utils/api"

export type ListPersonsResult = ListResult<Person, ...>
export type ListPersonsArg = ListArg<...>

const personApi = api.injectEndpoints({
    endpoints: build => ({
        listPersons: build.query<ListPersonsResult, ListPersonsArg>({
            query: search => ({
                url: buildUrl(personUrls.list, { search }),
                method: "GET",
            }),
            providesTags: tagData("Person", { includeListTag: true })
        })
    })
})

Defining a Create Endpoint

When defining a create endpoint, it's recommended to use the CreateResult and CreateArg type constructors. The endpoint should follow the naming convention create{model_name}, be defined as a mutation, use the method "POST", and name the query's arg as body. The URL should be set as the model's list URL. The tags should be invalidated by calling the tagData utility and providing the model's name as an argument and setting includeListTag to true.

import {
    type CreateArg,
    type CreateResult,
    tagData,
} from "codeforlife/utils/api"

export type CreatePersonResult = CreateResult<Person, ...>
export type CreatePersonArg = CreateArg<Person, ...>

const personApi = api.injectEndpoints({
    endpoints: build => ({
        createPerson: build.mutation<CreatePersonResult, CreatePersonArg>({
            query: body => ({
                url: personUrls.list,
                method: "POST",
                body,
            }),
            invalidatesTags: tagData("Person", { includeListTag: true })
        })
    })
})

Defining a Update Endpoint

When defining a update endpoint, it's recommended to use the UpdateResult and UpdateArg type constructors. The endpoint should follow the naming convention update{model_name}, be defined as a mutation, use the method "PATCH", and unpack the query's arg as ({ id, ...body }). To build the URL, the buildUrl utility should be called, providing the model's detail URL and id as a URL parameter. The tags should be invalidated by calling the tagData utility and providing the model's name as an argument and setting includeListTag to true.

import {
    type UpdateArg,
    type UpdateResult,
    buildUrl,
    tagData,
} from "codeforlife/utils/api"

export type UpdatePersonResult = UpdateResult<Person, ...>
export type UpdatePersonArg = UpdateArg<Person, ...>

const personApi = api.injectEndpoints({
    endpoints: build => ({
        updatePerson: build.mutation<UpdatePersonResult, UpdatePersonArg>({
            query: ({ id, ...body }) => ({
                url: buildUrl(personUrls.detail, { url: { id } }),
                method: "PATCH",
                body,
            }),
            invalidatesTags: tagData("Person", { includeListTag: true })
        })
    })
})

Defining a Destroy Endpoint

When defining a destroy endpoint, it's recommended to use the DestoryResult and DestroyArg type constructors. The endpoint should follow the naming convention destroy{model_name}, be defined as a mutation, use the method "DELETE", and name the query's arg as id. To build the URL, the buildUrl utility should be called, providing the model's detail URL and id as a URL parameter. The tags should be invalidated by calling the tagData utility and providing the model's name as an argument and setting includeListTag to true.

import {
    type DestroyArg,
    type DestroyResult,
    buildUrl,
    tagData,
} from "codeforlife/utils/api"

export type DestroyPersonResult = DestroyResult
export type DestroyPersonArg = DestroyArg<Person>

const personApi = api.injectEndpoints({
    endpoints: build => ({
        destroyPerson: build.mutation<DestroyPersonResult, DestroyPersonArg>({
            query: id => ({
                url: buildUrl(personUrls.detail, { url: { id } }),
                method: "DELETE",
            }),
            invalidatesTags: tagData("Person", { includeListTag: true })
        })
    })
})

Forms

Documentation coming soon

Defining Fields

Documentation coming soon

Submitting a Form

Documentation coming soon

Schemas

Documentation coming soon

Defining a Schema

Documentation coming soon

Components

Documentation coming soon

Defining a Component

Documentation coming soon

Reusing Components

Documentation coming soon

Pages

Documentation coming soon

Defining Routes

Documentation coming soon

Navigating to Routes

Documentation coming soon

Link Components

Documentation coming soon

Theme

Documentation coming soon

Extending the Theme

Documentation coming soon

Environment Variables

Documentation coming soon

Setting Env. Variables

Documentation coming soon

Importing Env. Variables

Documentation coming soon