Skip to content

Commit 3bdceb8

Browse files
AlemTuzlakAlemTuzlak
committed
The one where I add shortcuts to the docs
1 parent 7baf013 commit 3bdceb8

21 files changed

Lines changed: 1054 additions & 4 deletions

‎docs/posts/4.2.0/_index.mdx‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Quick Start
3+
hidden: true
4+
toc: false
5+
---
6+
7+
import Info from './info.tsx'
8+
9+
This documentation covers everything you need to know to get started with `remix-development-tools`.
10+
11+
## Prerequisites
12+
13+
- Remix version **2.8** or higher.
14+
- Your project needs to run on **ESM**. If you are using CommonJS, you will need to convert your project to ESM.
15+
- Remix has to run on **Vite**.
16+
17+
## Why ESM and Vite?
18+
19+
If you don't already know, Remix has become a Vite plugin. This means that Remix is now using Vite for bundling
20+
and development instead of their own custom solution. Due to this `remix-development-tools` is also built on top of
21+
Vite and uses it extensively.
22+
23+
In order to use the full feature-set of **Vite** the project has to run on ESM. This is because Vite exposes a websocket
24+
that **remix-development-tools** uses to communicate with the server. This websocket is **only** available in ESM projects
25+
because it's exposed by `import.meta` which is only available in ESM.
26+
27+
To avoid creating user confusion and giving you a subpar experience, we have decided to only support ESM projects running on Vite.
28+
29+
<Info>
30+
If you are using CommonJS non-Vite Remix app, you will need to convert your project to ESM. This is not as hard as it sounds.
31+
You can find a guide on how to do this [here](https://remix.run/docs/en/main/future/vite#migrating) and [here](https://alemtuzlak.hashnode.dev/migrating-a-v1-cjs-remix-project-to-remix-vite-esm)
32+
</Info>
33+
34+
## Why use `remix-development-tools`?
35+
36+
`remix-development-tools` is a set of tools that help you to develop your Remix application.
37+
38+
They help you, but are not limited to, to do the following things:
39+
- **Loader data display** - You can see the data that is being loaded by your loaders.
40+
- **Route display** - You can see the routes that are being used by your application in list/tree format.
41+
- **Error tracking** - You can see invalid HTML rendered on your page and where it's coming from.
42+
- **Hydration mismatch tracking** - You can see if there are any hydration mismatches in your application, what was rendered on the client and what was rendered on the server.
43+
- **Server logs** - You can see the logs of your server in the browser.
44+
- **Route boundaries** - You can see the route boundaries by hovering over elements.

‎docs/posts/4.2.0/configuration/client.mdx‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
title: Remix Development Tools Client Configuration
3+
description: Configuration options for the Remix Development Tools client
4+
---
5+
6+
import Info from "./info.tsx";
7+
import Warn from "./warn.tsx";
8+
9+
<Info>
10+
All of the following options can be set in the dev tools panel **"Settings page"** and they override the default ones. Your preferences are
11+
stored in localStorage and if they do not exist there the default ones are used.
12+
</Info>
13+
14+
Before we explain all the possible options here is the client configuration Typescript type:
15+
16+
```ts
17+
type RdtClientConfig = {
18+
position: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "middle-left" | "middle-right";
19+
defaultOpen: boolean;
20+
expansionLevel: number;
21+
height: number;
22+
minHeight: number;
23+
maxHeight: number;
24+
hideUntilHover: boolean;
25+
panelLocation: "top" | "bottom";
26+
requireUrlFlag: boolean;
27+
urlFlag: string;
28+
routeBoundaryGradient: "sea" | "hyper" | "gotham" | "gray" | "watermelon" | "ice" | "silver";
29+
}
30+
```
31+
32+
Let's go through each option and see what it does.
33+
34+
## Position
35+
36+
This option is used to set the position of the Remix Development Tools trigger (the button that opens the panel). The possible values are:
37+
- `top-left` - the trigger will be positioned at the top left corner of the screen
38+
- `top-right` - the trigger will be positioned at the top right corner of the screen
39+
- `bottom-left` - the trigger will be positioned at the bottom left corner of the screen
40+
- `bottom-right` - the trigger will be positioned at the bottom right corner of the screen
41+
- `middle-left` - the trigger will be positioned at the middle left of the screen
42+
- `middle-right` - the trigger will be positioned at the middle right of the screen
43+
44+
## Default Open
45+
46+
This option is used to set the initial state of the panel. If set to `true` the panel will be open by default, if set to `false`
47+
the panel will be closed by default.
48+
49+
## Expansion Level
50+
51+
This option is used to set the initial expansion level of the returned JSON data in the **Active Page** tab. By default it is set to
52+
0 and if you open up the **Active Page** and look at the returned loader data it will look like this:
53+
54+
```ts
55+
"data": { ... } +
56+
```
57+
58+
If you set the expansion level to 1 the returned loader data will look like this:
59+
60+
```ts
61+
"data": {
62+
"property": "value"
63+
}
64+
```
65+
66+
## Height
67+
68+
This option is used to set the initial height of the panel. The default value is 400px.
69+
70+
## Min Height
71+
72+
This option is used to set the minimum height of the panel. The default value is 200px.
73+
74+
## Max Height
75+
76+
This option is used to set the maximum height of the panel. The default value is 800px.
77+
78+
## Hide Until Hover
79+
80+
This option is used to set whether the trigger should be hidden until you hover over it. The default value is `false`.
81+
82+
## Panel Location
83+
84+
This option is used to set the location of the panel. The possible values are:
85+
- `top` - the panel will be positioned at the top of the screen
86+
- `bottom` - the panel will be positioned at the bottom of the screen
87+
88+
## Require URL Flag
89+
90+
This option is used to set whether the panel should be opened only if the URL contains a specific flag. The default value is `false`.
91+
92+
<Warn title="Be careful!">
93+
If you set this option to `true` and you forget to set the URL flag, the panel will hide and you will not be able to see it
94+
until you enter the url flag.
95+
96+
The default one is `rdt=true` and if you set this option to `true` you will have to add `?rdt=true` to the URL in order to see the panel.
97+
</Warn>
98+
99+
## URL Flag
100+
101+
This option is used to set the URL flag that is required to open the panel. The default value is `rdt`.
102+
103+
You can set it to whatever you wish and if you set the **Require URL Flag** option to `true` you will have to add `?yourFlag=true` to the URL in order to see the panel.
104+
105+
## Route Boundary Gradient
106+
107+
This option is used to set the color of the route boundary gradient. The possible values are:
108+
- `sea`
109+
- `hyper`
110+
- `gotham`
111+
- `gray`
112+
- `watermelon`
113+
- `ice`
114+
- `silver`
115+
116+
<Info>
117+
This changes the color of the route boundary gradient in the **Active Page** tab. When you hover over any route in the panel it will show you it's boundaries.
118+
</Info>
119+
120+
The default value is `ice`.
121+
122+
## Creating a custom configuration
123+
124+
To create a custom configuration you can use the following code snippet:
125+
126+
```ts
127+
import { defineRdtConfig } from "remix-development-tools";
128+
129+
const customConfig = defineRdtConfig({
130+
client: {
131+
position: "top-right",
132+
defaultOpen: true,
133+
expansionLevel: 1,
134+
height: 500,
135+
minHeight: 300,
136+
maxHeight: 1000,
137+
hideUntilHover: true,
138+
panelLocation: "bottom",
139+
requireUrlFlag: true,
140+
urlFlag: "customFlag",
141+
routeBoundaryGradient: "gotham",
142+
}
143+
});
144+
145+
export default customConfig;
146+
```
147+
148+
Then you can use this configuration in your `vite.config.js` file like this:
149+
150+
```ts
151+
import customConfig from "./rdt.config";
152+
import { remixDevTools } from "remix-development-tools";
153+
154+
export default defineConfig({
155+
plugins: [remixDevTools(customConfig)],
156+
});
157+
```
158+
159+
<Info title="Try it out!">
160+
Try opening up the dev tools panel deployed on this site and playing around with the settings in the settings tab!
161+
</Info>
162+

‎docs/posts/4.2.0/configuration/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Configuration
3+
order: 3
4+
---

‎docs/posts/4.2.0/configuration/server.mdx‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: Remix Development Tools Server Configuration
3+
description: Configuration options for the Remix Development Tools server
4+
---
5+
6+
import Info from "./info.tsx";
7+
import Warn from "./warn.tsx";
8+
9+
As with the client configuration, we will first see the full configuration type:
10+
11+
```ts
12+
interface RemixServerConfig {
13+
silent?: boolean;
14+
logs?: {
15+
cookies?: boolean;
16+
defer?: boolean;
17+
actions?: boolean;
18+
loaders?: boolean;
19+
cache?: boolean;
20+
siteClear?: boolean;
21+
};
22+
}
23+
```
24+
25+
## `silent`
26+
27+
When `true`, the server will not log anything to the console. This is useful for production environments.
28+
29+
## `logs`
30+
31+
This object allows you to configure the server logs. Each key is a log type and the value is a boolean indicating whether to log that type.
32+
All are `true` by default so you don't have to provide anything, if you want to be granular you can, otherwise you can use the `silent` option to turn off
33+
all logs.
34+
35+
### `cookies`
36+
37+
When `true`, the server will log all cookies sent by the server in the "Set-Cookie" header.
38+
39+
### `defer`
40+
41+
When `true`, the server will log all deferred actions.
42+
The following gets logged:
43+
- The defer location
44+
- The keys that were deferred
45+
- The time it took for each key to resolve
46+
47+
### `actions`
48+
49+
When `true`, the server will log all actions that are hit with a request.
50+
51+
### `loaders`
52+
53+
When `true`, the server will log all loaders that are hit with a request.
54+
55+
### `cache`
56+
57+
When `true`, the server will log all loaders/actions that return a `Cache Control` header.
58+
59+
### `siteClear`
60+
61+
When `true`, the server will log when the site cache is cleared, or anything else with the `Clear-Site-Data` header.

‎docs/posts/4.2.0/features/active-page-tab.mdx‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: "Active Page Tab"
3+
description: "Detailed overview of all features on the active page tab."
4+
---
5+
6+
import Info from "./info.tsx";
7+
8+
The Active Page tab is the first tab that appears when you open up the dev tools panel. It contains an overview of all active loaders
9+
on the current page and detailed information about each loader.
10+
11+
## Route boundaries
12+
13+
The first feature we will go over is the route boundaries. This feature shows you the current route boundaries on the actual page.
14+
This is useful for debugging and testing purposes. It finds the `<Outlet />` component in the route and highlights it with a
15+
gradient background that can be set in the settings.
16+
17+
<Info>
18+
This feature is only available in the development mode because it used react dev tools to find the `<Outlet />` component.
19+
20+
If you want to try it open up the dev tools right now nad hover over `/docs/main` in the panel.
21+
22+
You can also change the gradient background color in the settings.
23+
</Info>
24+
25+
## Loader list
26+
27+
The loader list is a list of all active loaders on the current page. It shows the url segment of the loader,
28+
the loader type and the loader file.
29+
30+
<Info>
31+
The loader type is determined by the routing convention.
32+
- `purple` - represents the root.tsx file
33+
- `blue` - represents a pathless layout file
34+
- `green` - represents a normal route file, whether index or not
35+
</Info>
36+
37+
### Open in VS code
38+
39+
Each segment has an **open in VS code** button that opens the loader file in VS code.
40+
This is useful for quick navigation to the loader file.
41+
42+
<Info title="Caveat!">
43+
This only works if you have the `code` command installed in your terminal. If you don't have it installed you can
44+
install it by following the instructions [here](https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line).
45+
</Info>
46+
47+
### Loader data
48+
49+
Each segment has a loader data **JSON** object that contains all the information returned by the loader of that segment.
50+
51+
If you open the dev tools on this page and look at the `/docs/main` segment you will see the **loader data object** which contains
52+
`metadata`, `tag`, `serverData`, `deferredServerData` and `key` properties.
53+
54+
This part will contain everything returned from the server and it will be **hot swapped** if the data changes.
55+
56+
<Info>
57+
When keys are deferred on the server, the data will hot swap when the key is resolved on the client.
58+
59+
</Info>
60+
61+
### Route params
62+
63+
The route params section contains all the route params for the current segment.
64+
65+
This will contain all the **wildcard** params currently available on this route.
66+
67+
If you open up the dev tools, you will be able to see that `tag` and `slug` are both in
68+
the route params.
69+
70+
### Server info
71+
72+
The server info section contains all the server information for the current segment, including:
73+
- `loaderTriggerCount` - the number of times the loader has been triggered (updates in real-time)
74+
- `actionTriggerCount` - the number of times the action has been triggered (updates in real-time)
75+
- `lowestExecutionTime` - the lowest execution time of the loader (updates in real-time)
76+
- `highestExecutionTime` - the highest execution time of the loader (updates in real-time)
77+
- `averageExecutionTime` - the average execution time of the loader (updates in real-time)
78+
- `lastLoaderInfo` - the last loader info object (updates in real-time), includes execution time, request headers and response headers.
79+
- `lastActionInfo` - the last action info object (updates in real-time), includes execution time, request headers and response headers.
80+
- `loaderCalls` - an array of loaderInfo objects ordered from most recent to least recent (updates in real-time)
81+
- `actionCalls` - an array of actionInfo objects ordered from most recent to least recent (updates in real-time)
82+
83+
### handles
84+
85+
The handles section contains all the handles for the current segment.
86+
87+
This will contain all the **handles** currently available on this route.
88+
89+
Remix allows you to export a custom **handle** export which can be anything, it will be shown here if it is exported.
90+
91+
## Revalidation
92+
93+
There is a **Revalidate** button that allows you to revalidate all the loaders on the page.
94+
95+
96+
## Timeline
97+
98+
The timeline section on the right contains useful information on navigation and submission events in your application.
99+
100+
Every time there is a navigation or submission event, a new entry will be added to the timeline on the top.
101+
102+
It is limited to 50 entries and will remove the oldest entry when the limit is reached.
103+
104+
The timeline will contain the following information for each event:
105+
- `type` - the type of event (navigation or submission, fetcher or normal)
106+
- `method` - the method of the event (GET, POST, PUT, DELETE)
107+
- `url` - the url of the event
108+
- `data sent` - the data sent in the event
109+
- `response` - the response of the event
110+
111+
<Info>
112+
This only happens for events that change the state of the app, if there is a client-side navigation to a
113+
new location that has no loaders nothing will happen because the state has remained idle.
114+
</Info>
115+
116+
### Clearing the timeline
117+
118+
You can clear the timeline by clicking the **clear** button at the top right of the timeline.

0 commit comments

Comments
 (0)