Skip to content

Commit 551412c

Browse files
gabrielmferncpenned
gabrielmfern
and
cpenned
authored
feat(docs): Improved contributing guide (#1342)
Co-authored-by: Chris Pennington <[email protected]> Co-authored-by: cpenned <[email protected]>
1 parent 7a6eec8 commit 551412c

13 files changed

+503
-31
lines changed

‎CONTRIBUTING.md

+15-20
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,23 @@
1-
## Contributing
1+
Thank you for considering contributing to React Email.
22

3-
Wanna help? Awesome! There are many ways you can contribute.
3+
We've created this guide to help you better understand how to contribute to the project, even if you've never contributed to an open source project before.
44

5-
## Improving the docs
5+
## How to report bugs
66

7-
Documentation is extremely important and takes a fair deal of time and effort to write and keep updated. Everything is written in Markdown to facilitate the process of contributing.
7+
To report a bug, please first read our guide on [opening issues](https://react.email/docs/contributing/opening-issues).
88

9-
## Building new components
9+
## How to contribute code
1010

11-
We’re open to expanding the catalog of components to cover as many use cases as possible. We suggest to open an issue for discussion first to make sure your idea is aligned with the project goals.
11+
To open a pull request, please first read our guide on [opening pull requests](https://react.email/docs/contributing/opening-pull-requests), which outlines our process for RFCs and pull requests.
1212

13-
## Opening issues
13+
### Codebase overview
14+
If you need help getting familiar with our codebase, we recommend reading our [Codebase overview guide](https://react.email/docs/contributing/codebase-overview).
1415

15-
Open an issue to report bugs or to propose new features.
16+
### Development workflow guide
17+
We have also created a Development workflow guide to help you get familiar with the development workflow for React Email. It includes instructions for:
18+
1. [Setting up your development environment](https://react.email/docs/contributing/development-workflow/1-setup)
19+
2. [Running tests](https://react.email/docs/contributing/development-workflow/2-running-tests)
20+
3. [Linting](https://react.email/docs/contributing/development-workflow/3-linting)
21+
4. [Building](https://react.email/docs/contributing/development-workflow/4-building)
22+
5. [Writing documentation](https://react.email/docs/contributing/development-workflow/5-writing-docs)
1623

17-
**- Reporting bugs:**
18-
describe the bug as clearly as you can, including steps to reproduce, what happened and what you were expecting to happen. Also include browser version, OS and other related software’s (npm, Node.js, etc) versions when applicable.
19-
20-
**- Suggesting features:** explain the proposed feature, what it should do, why it is useful, how users should use it. Give us as much info as possible so it will be easier to discuss, access and implement the proposed feature. When you’re unsure about a certain aspect of the feature, feel free to leave it open for others to discuss and find an appropriate solution.
21-
22-
## Proposing pull requests
23-
24-
Pull requests are very welcome. Note that if you are going to propose drastic changes, be sure to open an issue for discussion first, to make sure that your PR will be accepted before you spend effort coding it.
25-
26-
**- Forking the repository:** clone it locally and create a branch for your proposed bug fix or new feature. Avoid working directly on the main branch.
27-
28-
**- Making changes:** implement your bug fix or feature, write tests to cover it and make sure all tests are passing. Then commit your changes, push your bug fix/feature branch to the origin (your forked repo) and open a pull request to the upstream (the repository you originally forked)‘s main branch.

‎apps/docs/contributing.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: 'Contributing'
3-
sidebarTitle: 'Contributing'
3+
sidebarTitle: 'Old Contributing'
44
description: 'Wanna help? Awesome! There are many ways you can contribute.'
55
'og:image': 'https://react.email/static/covers/react-email.png'
66
icon: 'code-pull-request'

‎apps/docs/contributing/codebase-overview.mdx

+169
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: 'Codebase overview'
3+
sidebarTitle: 'Codebase overview'
4+
'og:image': 'https://react.email/static/covers/react-email.png'
5+
description: 'An overview of the React Email codebase'
6+
icon: 'folder-tree'
7+
---
8+
9+
We've created this guide to help new contributors understand and navigate the React Email codebase.
10+
11+
## Top-level directories
12+
13+
After cloning the [React Email repository](https://github.com/resend/react-email) you will see a few root-level directories. Here's a brief overview of each:
14+
15+
<table>
16+
<thead>
17+
<tr>
18+
<th>Directory</th>
19+
<th>Description</th>
20+
</tr>
21+
</thead>
22+
<tbody>
23+
<tr>
24+
<td>
25+
[apps](https://github.com/resend/react-email/tree/canary/apps)
26+
</td>
27+
<td>
28+
Here you can find all of the apps related to our online presence, like:
29+
- this documentation (under [apps/docs](https://github.com/resend/react-email/tree/canary/apps/docs)),
30+
- the demo emails we have on [demo.react.email](https://demo.react.email/preview/vercel-invite-user.tsx)
31+
(under [apps/demo](https://github.com/resend/react-email/tree/canary/apps/demo))
32+
- the Next app we have for our landing page on [react.email](https://react.email) (under [apps/web](https://github.com/resend/react-email/tree/canary/apps/web))
33+
</td>
34+
</tr>
35+
<tr>
36+
<td>
37+
[benchmarks](https://github.com/resend/react-email/tree/canary/benchmarks)
38+
</td>
39+
<td>
40+
We make benchmarks from version-to-version to demonstrate data-observable performance gains with metrics like *p99 and p75*.
41+
42+
For example, see the [Improved Performance for Tailwind Emails](https://resend.com/blog/improved-performance-for-tailwind-emails) benchmark.
43+
</td>
44+
</tr>
45+
<tr>
46+
<td>
47+
[packages](https://github.com/resend/react-email/tree/canary/packages)
48+
</td>
49+
<td>
50+
Most contributions will be made to the packages in this directory.
51+
52+
This directory contains all our published [NPM](https://www.npmjs.com/) packages.
53+
Each subdirectory is a single component published as its own package, with the exception of a few packages that serve as shared configuration.
54+
</td>
55+
</tr>
56+
</tbody>
57+
</table>
58+
59+
<Note>
60+
Feel free to [open a discussion](https://github.com/resend/react-email/discussions/new?category=ideas) if you have suggestions on how to better structure these packages to make them more manageable and approachable.
61+
</Note>
62+
63+
## Multiple packages
64+
65+
The react-email repository is a [pnpm monorepo](https://pnpm.io/next/workspaces), which means it contains
66+
multiple packages.
67+
68+
Because we use pnpm, you will need to use [pnpm](https://pnpm.io/) to install and run each package. If you do not have pnpm installed, we recommend you install it using [corepack](https://github.com/nodejs/corepack):
69+
70+
```bash
71+
corepack enable
72+
corepack prepare pnpm@latest --activate
73+
```
74+
75+
Currently, we have the following packages:
76+
77+
<div className="grid gap-2" style={{ gridTemplateColumns: '1fr 1fr 1fr' }}>
78+
<div>
79+
- [@react-email/body](https://github.com/resend/react-email/tree/canary/packages/body)
80+
- [@react-email/button](https://github.com/resend/react-email/tree/canary/packages/button)
81+
- [@react-email/code-block](https://github.com/resend/react-email/tree/canary/packages/code-block)
82+
- [@react-email/code-inline](https://github.com/resend/react-email/tree/canary/packages/code-inline)
83+
- [@react-email/column](https://github.com/resend/react-email/tree/canary/packages/column)
84+
- [@react-email/components](https://github.com/resend/react-email/tree/canary/packages/components)
85+
- [@react-email/container](https://github.com/resend/react-email/tree/canary/packages/container)
86+
- [create-email](https://github.com/resend/react-email/tree/canary/packages/create-email)
87+
- <span className="text-xs">Used for our [automatic setup](/getting-started/automatic-setup)</span>
88+
</div>
89+
<div>
90+
- [@react-email/font](https://github.com/resend/react-email/tree/canary/packages/font)
91+
- [@react-email/head](https://github.com/resend/react-email/tree/canary/packages/head)
92+
- [@react-email/heading](https://github.com/resend/react-email/tree/canary/packages/heading)
93+
- [@react-email/hr](https://github.com/resend/react-email/tree/canary/packages/hr)
94+
- [@react-email/html](https://github.com/resend/react-email/tree/canary/packages/html)
95+
- [@react-email/img](https://github.com/resend/react-email/tree/canary/packages/img)
96+
- [@react-email/link](https://github.com/resend/react-email/tree/canary/packages/link)
97+
- [@react-email/markdown](https://github.com/resend/react-email/tree/canary/packages/markdown)
98+
- [@react-email/preview](https://github.com/resend/react-email/tree/canary/packages/preview)
99+
</div>
100+
<div>
101+
- [react-email](https://github.com/resend/react-email/tree/canary/packages/react-email)
102+
- <span className="text-xs">The package for our [email CLI](/cli)</span>
103+
- [@react-email/render](https://github.com/resend/react-email/tree/canary/packages/render)
104+
- [@react-email/row](https://github.com/resend/react-email/tree/canary/packages/row)
105+
- [@react-email/section](https://github.com/resend/react-email/tree/canary/packages/section)
106+
- [@react-email/tailwind](https://github.com/resend/react-email/tree/canary/packages/tailwind)
107+
- [@react-email/text](https://github.com/resend/react-email/tree/canary/packages/text)
108+
</div>
109+
</div>
110+
111+
Most of these packages are very small and can be easily understood by reading the code, so feel free to explore.
112+
113+
### Turborepo
114+
115+
We encourage using [turborepo](https://turbo.build/repo) to manage the packages.
116+
117+
It's often helpful to [install Turborepo globally](https://turbo.build/repo/docs/installing) to make it easier to run commands in any of the repositories. With a global installation, running `turbo build` in any of the packages will build both the package
118+
you are on as well as the dependent packages. The global installation handles [version mismatching as well](https://turbo.build/repo/docs/installing#install-per-repository).
119+
120+
### The React Email CLI
121+
122+
The CLI (i.e. `packages/react-email`) is key to the best development experience with react.email, but it is complex. Here is a brief overview of the CLI.
123+
124+
The CLI includes two components:
125+
- A Next app for the `email dev` and `email build` commands
126+
- A [commander.js](https://www.npmjs.com/package/commander) CLI
127+
128+
In the NextJS app, we include a `src/cli` directory that is not published but is compiled into a root `cli` directory. This structure provides a good developer experience as we can both share certain functions and communicate between the CLI components.
129+
130+
We trigger rebuilds of email templates after they have been saved using the
131+
[chokidar](https://www.npmjs.com/package/chokidar) package
132+
alongside the [socket.io](https://socket.io/) package to detect file changes and send
133+
a message to the server to trigger a rebuild.
134+
135+
## Testing
136+
137+
For testing, we use [vitest](https://vitest.dev/). We prefer to define globals and run tests under the `happy-dom` environment.
138+
139+
We do not strictly enforce testing coverage, but encourage it.
140+
141+
For help testing, see our [Development workflow guide](/contributing/development-workflow/2-running-tests).
142+
143+
<Note>
144+
The `@react-email/render` package's `renderAsync` does a fair bit of magic to simulate `edge` and other environments that are not supported by `happy-dom`. For this use case, we override the [environment on a per-file basis](https://vitest.dev/guide/environment#environments-for-specific-files) for its tests
145+
</Note>
146+
147+
## Linting
148+
149+
We use [biomejs](https://biomejs.dev/) for linting and formatting. Both the linting and formatting are ensured by our GitHub CI so make sure you lint and format your code (`pnpm lint:fix`) before opening a PR or asking for a review on it.
150+
151+
For help linting and formatting, see our [Development workflow guide on linting](/contributing/development-workflow/3-linting).
152+
153+
## Building
154+
155+
We use [tsup](https://github.com/egoist/tsup) to build most packages. (The only exception for this is the `@react-email/tailwind` package which currently uses `vite` due to a few issues with `tsup` and `tailwindcss`'s bundling.) For help building packages, see our [Development workflow guide](/contributing/development-workflow/4-building).
156+
157+
<Note>
158+
Building in each package will run `tsup` with a few settings, typically `src/index.ts --format esm,cjs --dts --external react`.
159+
Tsup handles building both ESM and CJS versions along with the type definitions exported from the entry point, `src/index.ts`, without bundling `react`, which can cause issues.
160+
</Note>
161+
162+
### Why build before publishing?
163+
164+
We build most of the packages before publishing for a few reasons:
165+
166+
1. All the exported types can be imported from the same place the JavaScript is imported
167+
2. We have proper [CommonJS](https://nodejs.org/docs/latest/api/modules.html#modules-commonjs-modules)
168+
and [ES Modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules) support
169+
3. Code that isn't exported is not published or downloaded

‎apps/docs/contributing/development-workflow/1-setup.mdx

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: 'Setup'
3+
sidebarTitle: '1. Setup'
4+
'og:image': 'https://react.email/static/covers/react-email.png'
5+
description: 'Things you will need to do beforehand to setup the project'
6+
---
7+
8+
Before you can start developing, you will need to get the project setup.
9+
10+
<Info>
11+
To contribute to the project, you must use **Node 18** or higher.
12+
</Info>
13+
14+
<Steps>
15+
<Step title="Clone the repository">
16+
```bash
17+
git clone https://github.com/resend/react-email
18+
```
19+
</Step>
20+
<Step title={<>Enable <a href="https://pnpm.io/">pnpm</a> through <a href="https://github.com/nodejs/corepack">corepack</a></>}>
21+
```bash inside of react-email
22+
corepack enable
23+
corepack prepare pnpm@latest --activate
24+
```
25+
</Step>
26+
<Step title="Install all the dependencies">
27+
```bash inside of react-email
28+
pnpm install
29+
```
30+
</Step>
31+
<Step title="Build all the packages">
32+
```bash inside of react-email
33+
pnpm build
34+
```
35+
36+
<Note>
37+
Building first is crucial because each package may depend on other packages, and pre-building them will ensure that you don't run into issues when developing.
38+
</Note>
39+
</Step>
40+
</Steps>
41+
42+
If you plan to contribute to the docs, view our [Writing docs](/contributing/development-workflow/5-writing-docs) guide for additional setup.
43+
44+
If you have have any trouble, please [reach out on Discord](https://discord.com/invite/n2pWEjjNnD) or consider [opening up an issue on GitHub](https://github.com/resend/react-email/issues/new?assignees=&labels=Type%3A+Bug&projects=&template=1.bug_report.yml) after reading the [issue guidelines](/contributing/opening-issues).

‎apps/docs/contributing/development-workflow/2-running-tests.mdx

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: 'Running tests'
3+
sidebarTitle: '2. Running tests'
4+
'og:image': 'https://react.email/static/covers/react-email.png'
5+
description: 'Everything you need to know about our testing setup and strategy'
6+
---
7+
8+
For testing, we use [vitest](https://vitest.dev/). We prefer to define globals and run tests under the `happy-dom` environment.
9+
10+
<Note>
11+
The `@react-email/render` package's `renderAsync` does a fair bit of magic to simulate `edge` and other environments that are not supported by `happy-dom`. For this use case, we override the [environment on a per-file basis](https://vitest.dev/guide/environment#environments-for-specific-files) for its tests
12+
</Note>
13+
14+
We do not strictly enforce testing coverage, but encourage it. A good rule of thumb is that if you need to simulate use
15+
cases to check whether a specific portion of code works, you should split it into a function with a matching unit test.
16+
17+
After you have gone through the [setup](/contributing/development-workflow/1-setup) run
18+
`pnpm test` inside any package. This will run the tests only once. We have two
19+
scripts defined on our packages for testing:
20+
21+
- `pnpm test`: Runs all the tests once. If you run it on the root, it will run the
22+
tests for all packages using
23+
[turborepo](/contributing/codebase-overview#turborepo)
24+
- `pnpm test:watch`: Runs all the tests and watches for changes. Vitest
25+
automatically only runs the tests that are affected by the code you've
26+
changed.

‎apps/docs/contributing/development-workflow/3-linting.mdx

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: 'Linting'
3+
sidebarTitle: '3. Linting'
4+
'og:image': 'https://react.email/static/covers/react-email.png'
5+
description: 'Everything you need to know about linting and formatting'
6+
---
7+
8+
We use [biomejs](https://biomejs.dev/) for linting and formatting. Both linting and formatting are ensured by our GitHub CI, so before opening a PR or asking for a review, please lint and format your code.
9+
10+
## Check for linting issues
11+
To check if there are any linting issues, run `pnpm lint` on the root of the workspace.
12+
13+
```bash
14+
pnpm lint
15+
```
16+
17+
To lint or format the entire project, run `pnpm lint:fix` on the root of the workspace.
18+
19+
```bash
20+
pnpm lint:fix
21+
```
22+
23+
Both the linting and formatting are ensured by our GitHub CI so make sure you lint and format your code before opening a PR or asking for a review on it.

‎apps/docs/contributing/development-workflow/4-building.mdx

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: "Building"
3+
sidebarTitle: "4. Building"
4+
"og:image": "https://react.email/static/covers/react-email.png"
5+
description: "How we build each package before publishing"
6+
---
7+
8+
We use [tsup](https://github.com/egoist/tsup) to build most packages. (The only exception for this is the `@react-email/tailwind` package which currently uses `vite` due to a few issues with `tsup` and `tailwindcss`'s bundling.)
9+
10+
To build a package run:
11+
12+
```bash package/* (ex: package/render)
13+
pnpm build
14+
```
15+
16+
Building in each package will run `tsup` with a few settings, typically `src/index.ts --format esm,cjs --dts --external react`.
17+
Tsup handles building both [ESM](https://nodejs.org/api/esm.html) and
18+
[CJS](https://nodejs.org/docs/latest/api/modules.html) versions along with the type definitions exported from the entry point, `src/index.ts`, without bundling `react`, which can cause issues.
19+
20+
### Why build before publishing?
21+
22+
We build most of the packages before publishing for a few reasons:
23+
24+
1. All the exported types can be imported from the same place the JavaScript is imported
25+
2. We have proper [CommonJS](https://nodejs.org/docs/latest/api/modules.html#modules-commonjs-modules)
26+
and [ES Modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules) support
27+
3. Code that isn't exported is not published or downloaded

‎apps/docs/contributing/development-workflow/5-writing-docs.mdx

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: '5. Writing docs'
3+
sidebarTitle: '5. Writing docs'
4+
'og:image': 'https://react.email/static/covers/react-email.png'
5+
---
6+
7+
We use [Mintlify](https://mintlify.com/) for our documentation.
8+
9+
To preview the docs, you just need to run:
10+
11+
```sh apps/docs
12+
pnpm dev
13+
```
14+
15+
Check out [Mintlify's development guide](https://mintlify.com/docs/development)
16+
for a few more interesting development tools.
17+
18+
## Components
19+
20+
Mintlify uses `mdx` to allow us to write docs in a composable ways. Because of
21+
`mdx`, we can build [our own
22+
components](https://mintlify.com/docs/reusable-snippets#reusable-components)
23+
but it's always best to use the components Mintlify already provides us. Before writing down a new component, check their [full list of components](https://mintlify.com/docs/content/components).
24+

0 commit comments

Comments
 (0)