Skip to content

Commit 82b3b53

Browse files
AlemTuzlakAlemTuzlak
authored
Breakpoint feature added (forge-42#147)
* Breakpoint feature added * docs update * update
1 parent fb9c1af commit 82b3b53

28 files changed

+1266
-7
lines changed

‎docs/posts/4.6.0/_index.mdx

+44
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.6.0/configuration/client.mdx

+195
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
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+
liveUrls: { name: string, url: string }[];
20+
liveUrlsPosition: "top-left" | "top-right" | "bottom-left" | "bottom-right";
21+
defaultOpen: boolean;
22+
expansionLevel: number;
23+
height: number;
24+
minHeight: number;
25+
maxHeight: number;
26+
hideUntilHover: boolean;
27+
panelLocation: "top" | "bottom";
28+
requireUrlFlag: boolean;
29+
urlFlag: string;
30+
breakpoints: {name: string, min: number, max: number }[],
31+
routeBoundaryGradient: "sea" | "hyper" | "gotham" | "gray" | "watermelon" | "ice" | "silver";
32+
showBreakpointIndicator: boolean;
33+
}
34+
```
35+
36+
Let's go through each option and see what it does.
37+
38+
## Live URLs
39+
40+
This option is used to set the live urls that will be displayed in the bottom left corner of the screen. The default value is an empty array.
41+
It allows you to specify multiple live urls that you can use to open the current page in a new tab.
42+
43+
## Live URLs position
44+
45+
This option is used to set the position of the live urls that will be displayed in the bottom left corner of the screen. The possible values are:
46+
- `top-left` - the live urls will be positioned at the top left corner of the screen
47+
- `top-right` - the live urls will be positioned at the top right corner of the screen
48+
- `bottom-left` - the live urls will be positioned at the bottom left corner of the screen
49+
- `bottom-right` - the live urls will be positioned at the bottom right corner of the screen
50+
51+
## Position
52+
53+
This option is used to set the position of the Remix Development Tools trigger (the button that opens the panel). The possible values are:
54+
- `top-left` - the trigger will be positioned at the top left corner of the screen
55+
- `top-right` - the trigger will be positioned at the top right corner of the screen
56+
- `bottom-left` - the trigger will be positioned at the bottom left corner of the screen
57+
- `bottom-right` - the trigger will be positioned at the bottom right corner of the screen
58+
- `middle-left` - the trigger will be positioned at the middle left of the screen
59+
- `middle-right` - the trigger will be positioned at the middle right of the screen
60+
61+
## Default Open
62+
63+
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`
64+
the panel will be closed by default.
65+
66+
## Expansion Level
67+
68+
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
69+
0 and if you open up the **Active Page** and look at the returned loader data it will look like this:
70+
71+
```ts
72+
"data": { ... } +
73+
```
74+
75+
If you set the expansion level to 1 the returned loader data will look like this:
76+
77+
```ts
78+
"data": {
79+
"property": "value"
80+
}
81+
```
82+
83+
## Height
84+
85+
This option is used to set the initial height of the panel. The default value is 400px.
86+
87+
## Min Height
88+
89+
This option is used to set the minimum height of the panel. The default value is 200px.
90+
91+
## Max Height
92+
93+
This option is used to set the maximum height of the panel. The default value is 800px.
94+
95+
## Hide Until Hover
96+
97+
This option is used to set whether the trigger should be hidden until you hover over it. The default value is `false`.
98+
99+
## Panel Location
100+
101+
This option is used to set the location of the panel. The possible values are:
102+
- `top` - the panel will be positioned at the top of the screen
103+
- `bottom` - the panel will be positioned at the bottom of the screen
104+
105+
## Require URL Flag
106+
107+
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`.
108+
109+
<Warn title="Be careful!">
110+
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
111+
until you enter the url flag.
112+
113+
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.
114+
</Warn>
115+
116+
## URL Flag
117+
118+
This option is used to set the URL flag that is required to open the panel. The default value is `rdt`.
119+
120+
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.
121+
122+
## Route Boundary Gradient
123+
124+
This option is used to set the color of the route boundary gradient. The possible values are:
125+
- `sea`
126+
- `hyper`
127+
- `gotham`
128+
- `gray`
129+
- `watermelon`
130+
- `ice`
131+
- `silver`
132+
133+
<Info>
134+
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.
135+
</Info>
136+
137+
The default value is `ice`.
138+
139+
## Breakpoints
140+
141+
This option allows you to define custom breakpoints that show in the bottom left corner of the panel to help you determine the current screen breakpoint you have defined.
142+
By default the breakpoints are set to tailwind breakpoints but you can change them to whatever you want.
143+
144+
Eg:
145+
```ts
146+
breakpoints: [{name: "lg", min: 0, max: 768}, {name: "xl", min: 768, max: 1024}, {name: "2xl", min: 1024, max: Infinity}],
147+
```
148+
149+
## Show breakpoint indicator
150+
151+
This option allows you to show/hide the current breakpoint in the bottom left corner of the panel.
152+
153+
## Creating a custom configuration
154+
155+
To create a custom configuration you can use the following code snippet:
156+
157+
```ts
158+
import { defineRdtConfig } from "remix-development-tools";
159+
160+
const customConfig = defineRdtConfig({
161+
client: {
162+
position: "top-right",
163+
defaultOpen: true,
164+
expansionLevel: 1,
165+
height: 500,
166+
minHeight: 300,
167+
maxHeight: 1000,
168+
hideUntilHover: true,
169+
panelLocation: "bottom",
170+
requireUrlFlag: true,
171+
urlFlag: "customFlag",
172+
routeBoundaryGradient: "gotham",
173+
breakpoints: [{name: "lg", min: 0, max: 768}, {name: "xl", min: 768, max: 1024}, {name: "2xl", min: 1024, max: Infinity}],
174+
showBreakpointIndicator: false
175+
}
176+
});
177+
178+
export default customConfig;
179+
```
180+
181+
Then you can use this configuration in your `vite.config.js` file like this:
182+
183+
```ts
184+
import customConfig from "./rdt.config";
185+
import { remixDevTools } from "remix-development-tools";
186+
187+
export default defineConfig({
188+
plugins: [remixDevTools(customConfig)],
189+
});
190+
```
191+
192+
<Info title="Try it out!">
193+
Try opening up the dev tools panel deployed on this site and playing around with the settings in the settings tab!
194+
</Info>
195+

‎docs/posts/4.6.0/configuration/editor.mdx

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: Remix Development Tools Editor Configuration
3+
description: Configuration options for the Remix Development Tools to interface with your editor
4+
---
5+
6+
Everyone uses their own editors, so it's important to be able to configure the editor that Remix Development Tools will open your files in.
7+
8+
```ts
9+
type EditorConfig = {
10+
name: string;
11+
open(path: string, lineNumber: string | undefined): void;
12+
}
13+
```
14+
15+
## `name`
16+
17+
The name of the editor that will be displayed on the Open in Editor button.
18+
19+
## `open`
20+
21+
This function will be called when the user clicks the Open in Editor button. It will receive the path to the file and the line number to open the file at.
22+
This function will both handle the case where you shift + right click an element on the page AND the open in X button in the UI, they return different values
23+
so be sure to cover both of them.
24+
25+
```ts
26+
import { exec } from "node:child_process";
27+
import { normalizePath } from "vite";
28+
29+
function open(path: string, lineNumber: string | undefined) {
30+
exec(`code -g "${normalizePath(path)}${lineNumber ? `:${lineNumber}` : ""}"`);
31+
}
32+
```
33+
34+
## Editors
35+
36+
Below are some examples of configurations for popular editors.
37+
38+
### VS Code
39+
40+
To use VS Code as your editor, you don't need to do anything, it's the default editor.
41+
42+
### WebStorm
43+
44+
To use WebStorm as your editor, you can use the following configuration:
45+
46+
```ts
47+
import { exec } from "node:child_process";
48+
import { cwd } from "node:process";
49+
50+
const editor = {
51+
name: "WebStorm",
52+
open(path, lineNumber) {
53+
exec(
54+
`webstorm "${process.cwd()}/${path}" --line ${lineNumber ? `--line ${lineNumber}` : ""}`.replace(
55+
/\$/g,
56+
"\\$",
57+
),
58+
);
59+
},
60+
};
61+
```
62+
63+
### GoLand
64+
65+
To use WebStorm as your editor, you can use the following configuration:
66+
67+
```ts
68+
import { exec } from "node:child_process";
69+
import { cwd } from "node:process";
70+
71+
const editor = {
72+
name: "WebStorm",
73+
open(path, lineNumber) {
74+
if (!path) return;
75+
exec(
76+
`goland "${process.cwd()}/${path}" ${lineNumber ? `--line ${lineNumber}` : ""}`
77+
);
78+
},
79+
};
80+
```

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

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Configuration
3+
order: 3
4+
---

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

+61
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.

0 commit comments

Comments
 (0)