Unverified Commit b84bd522 authored by Jiwon Choi's avatar Jiwon Choi Committed by GitHub

[dev-overlay] docs: add readme (#76396)

This PR added the README for the dev overlay for future contributors.

[**View
Preview**](https://github.com/vercel/next.js/blob/9136b280a3e194b81c1ea9e4aa7236eeb895a843/packages/next/src/client/components/react-dev-overlay/README.md)

Closes NDX-656

---------
Co-authored-by: 's avatarLee Robinson <lee@leerob.com>
parent 025657cf
...@@ -98,6 +98,10 @@ Afterwards, you'll need to unpack the tarball into your test project. You can ei ...@@ -98,6 +98,10 @@ Afterwards, you'll need to unpack the tarball into your test project. You can ei
$ pnpm unpack-next path/to/project $ pnpm unpack-next path/to/project
``` ```
## Developing the Dev Overlay
The dev overlay is a feature of Next.js that allows you to see the internal state of the app including the errors. To learn more about contributing to the dev overlay, see the [Dev Overlay README.md](../../packages/next/src/client/components/react-dev-overlay/README.md).
## Recover disk space ## Recover disk space
Rust builds quickly add up to a lot of disk space, you can clean up old artifacts with this command: Rust builds quickly add up to a lot of disk space, you can clean up old artifacts with this command:
......
TODO # Dev Overlay
### Folder Structure ## Project Structure
- `ui` - This should be isolated from the rest of the codebase to make it easier to be excluded from compiliation and be bundled. - `app/` - Main entrypoint and related files for App Router dev overlay.
- `font/` - Includes Geist fonts that will be served to the client via the internal `/__nextjs_font/...` route.
- `pages/` - Main entrypoint and related files for Pages Router dev overlay.
- `server/` - Source files related to the dev overlay that are to run on the server and not sent to the client.
- `ui/` - Main source files that build the UI of the dev overlay. It is recommended to keep this directory isolated from the rest of the codebase to make it easier to be excluded from compiliation and be bundled in the future.
- `utils/` - Utils that can also be used outside of this project unlike the ones inside the `ui/` directory.
## Development
The dev overlay leverages [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) to insert the dev overlay into the client without affecting the user's application through encapsulation from CSS.
### Local Development
Next.js uses [Storybook](https://storybook.js.org) to develop UI components in the dev overlay.
To run the dev overlay locally, you can run the following command:
```bash
pnpm storybook
```
This will start the Storybook server at `http://localhost:6006`.
### Styling ### Styling
- The entrypoint needs to use `css` util that minifies styles. Next.js direcly injects CSS into the DOM via `<style>` tag. The styles will not affect the user's application as the [styles are encapsulated](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#encapsulation_from_css) from the rest of the application.
- Entrypoint is which are using `<style>` tag to inject styles.
> [!TIP]
> While Shadow DOM provides style encapsulation, the root element (i.e., `<nextjs-portal>`) can still inherit styles from parent elements like `<body>` or `<html>`. Direct styling on these parent elements (e.g., `body { contain: layout; }`) will affect the dev overlay.
Write CSS in template literals alongside your components. It is recommended to use the class names that are unique within the dev overlay to avoid conflicts. You can use `data-nextjs-` data attributes to target the elements in the dev overlay.
```tsx
export function Component() {
return (
<div className="some-unique-class-name">
<h1>Hello, Next.js!</h1>
</div>
)
}
export const COMPONENT_NAME_STYLES = `
.some-unique-class-name {
background-color: red;
}
`
```
> [!IMPORTANT]
> Use the `css()` util that minifies and removes the comments before injecting to the `<style>` tag.
The exported `COMPONENT_NAME_STYLES` can be used in the styles entrypoint (i.e., `ComponentStyles`) of the dev overlay to inject into the `<style>` tag.
```tsx
import { COMPONENT_NAME_STYLES } from './component'
export function ComponentStyles() {
return (
<style>
{css`
// ...
${COMPONENT_NAME_STYLES}
`}
</style
)
}
```
...@@ -33,6 +33,7 @@ const CHANGE_ITEM_GROUPS = { ...@@ -33,6 +33,7 @@ const CHANGE_ITEM_GROUPS = {
'packages/create-next-app/README.md', 'packages/create-next-app/README.md',
'packages/font/README.md', 'packages/font/README.md',
'packages/next-env/README.md', 'packages/next-env/README.md',
'packages/next/src/client/components/react-dev-overlay/README.md',
], ],
'deploy-examples': ['examples/image-component'], 'deploy-examples': ['examples/image-component'],
cna: [ cna: [
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment