From 98952a5b7562b2e79ebcd9b396a4f54d36428f99 Mon Sep 17 00:00:00 2001
From: Gabriel Miranda <gabrielmfern@outlook.com>
Date: Mon, 18 Mar 2024 13:50:23 -0300
Subject: [PATCH] feat(docs): More info on the `email dev` command (#1283)

---
 apps/docs/cli.mdx | 120 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 117 insertions(+), 3 deletions(-)

diff --git a/apps/docs/cli.mdx b/apps/docs/cli.mdx
index 0761f58c01..f7e62e5c82 100644
--- a/apps/docs/cli.mdx
+++ b/apps/docs/cli.mdx
@@ -8,9 +8,123 @@ icon: 'square-terminal'
 
 ## `email dev`
 
-Starts a local development server that will watch your files and automatically rebuild your email when you make changes.
+Starts a local development server that will watch your files and automatically rebuild 
+your email template when you make changes.
 
-**Options**
+### Where can I place my static files for previewing?
+
+Almost always you will need to have static files in your emails, and seeing
+them on the preview server without having to first host on a CDN is very helpful.
+
+We do allow for this, and currently, you can place your files inside a `static` 
+directory inside your `emails` directory. 
+
+This does adjust to your `--dir` option, so if your `emails` directory was inside
+`./src/emails`, you would place your static files inside `./src/emails/static`.
+
+These static files are directly served from our preview server by looking into the
+requests made into it that end with `/static` (i.e. `http://localhost:3000/static/...`) and serving the files at that point,
+this also allows for you to have images inside your emails like so:
+
+```jsx
+export default function Email(props) {
+  return (
+    <div>
+      <img src="/static/email-logo.png" />
+    </div>
+  )
+}
+```
+
+<Info>
+  This does not mean your images are hosted for you to send the emails.
+
+  If you do send the rendered email, and you are trying to link to an image, 
+  or some other asset inside `emails/static`, they will not load on the email that was sent.
+
+  We recommend that you use a different source link to your files depending on whether you're
+  running in production or not. Here's an example
+
+```jsx
+const baseURL = process.env.NODE_ENV === 'production' 
+  ? 'https://cdn.com' 
+  : ''
+
+export default function Email(props) {
+  return (
+    <div>
+      <img src={`${baseURL}/static/email-logo.png`} />
+    </div>
+  )
+}
+```
+  You can refer to our [demo emails source code](https://demo.react.email/preview/vercel-invite-user.tsx?view=source) 
+  for an example of how we do this with our demo deploy on Vercel.
+</Info>
+
+### How can I define props specific to the email's preview?
+
+Considering that you are already default exporting the React component
+that will render as your email template, you can just define a `PreviewProps` with it as follows:
+
+```jsx Email template
+export default function Email(props) {
+  return (
+    <div>
+      <a src={props.source}>click here if you want candy 👀</a>
+    </div>
+  )
+}
+
+Email.PreviewProps = {
+  source: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
+}
+```
+
+And then, when opening this email's preview, the `PreviewProps` will be used as props into Email. 
+So, in a nutshell, it will render the same as if you were to do:
+
+```jsx Another file
+import Email from './path-to-my-email';
+
+<Email {...Email.PreviewProps} />
+```
+
+### How to make the preview server ignore directories?
+
+Once the preview server has started and is now open on `localhost`, the preview server
+reads recursively down into all of your files and directories. This can be disabled
+from a directory down by prefixing it with `_`, e.g. `components -> _components`. 
+
+So if you wanted to make components for your emails, you could have a file structure as follows:
+
+```bash
+my-project
+├── emails
+│   ├── _components
+│   │   └── this-is-not-going-to-appear-in-the-sidebar.tsx
+│   ├── email.tsx
+│   └── static
+├── package.json
+└── tsconfig.json
+```
+
+Then the only file that will be shown on the preview server is going to be your `email.tsx`.
+
+### The heuristics for files to be considered emails
+
+To avoid uncanny files appearing in the sidebar of the preview server,
+we account for two heuristics to determine weather or not we should
+include it:
+
+1. If a file has `.js, .jsx or .tsx` as their file extension
+2. If the file contains a `export default` expression by matching with the regex<br/>
+`/\bexport\s*default\b/gm`
+
+These can certainly fail as they are only heuristics, so if you do find
+any issues with these, feel free to open an [issue](https://github.com/resend/react-email/issues).
+
+### Options
 
 <ResponseField name="--dir" type="string" default="emails">
   Change the directory of your email templates.
@@ -32,7 +146,7 @@ Copies the preview app for onto `.react-email` and builds it.
 
 ## `email start`
 
-Runs the built preview app that is inside of `.react-email`.
+Runs the built preview app that is inside `.react-email`.
 
 ## `email export`