Skip to content

Update README.md #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
paulftw wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Update README.md #78

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ed5b7d8
Update README.md
paulftw Aug 20, 2025
457022e
Fix new typo, remove unnecessary code
paulftw Aug 20, 2025
0f13437
fix wording about usage
paulftw Aug 20, 2025
b933845
make sure you -> make sure to
paulftw Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 24 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,9 +211,31 @@ ipyreact.ValueWidget(
)
```

### Importing ReactJS based libraries

Imported libraries must use the `react` and `react-dom` packages provided by `ipyreact`, otherwise things will break (see [FAQ](#faq)).
For esm.sh it can be achieved by adding `external=react,react-dom` to the URL:

```python
import ipyreact

class Doodle(ipyreact.ValueWidget):
_esm = """
import { MeditatingDoodle } from "https://esm.sh/react-open-doodles?external=react,react-dom";
import * as React from "react";

export default () => (
<div style={{width: 300}}>
<MeditatingDoodle accent="#0057B7" ink="#FFDD00" />
</div>
);
"""
Doodle()
```

### Import maps

However, the above code now has a direct link to "https://esm.sh/[email protected]" which makes the code very specific to esm.sh.
The above examples have direct links to esm.sh, e.g. "https://esm.sh/[email protected]". Which means version and CDN information is embedded in every component's code.

To address this, we also support [import maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to
write code more independant of where the modules come from.
Expand All @@ -230,8 +252,6 @@ define_import_map({
})
```

_Note that it is important to add `external=react,react-dom` for ReactJS based libraries, otherwise [esm.sh](https://esm.sh/#using-import-maps) would import ReactJS again_.

Which means we can now write our ConfettiButton as:

```python
Expand Down Expand Up @@ -464,7 +484,7 @@ React render tree.

For instance, if you see `"Cannot read properties of null (reading 'useReducer')"` it means that you are loading in your own ReactJS version.

If you use https://esh.sh, make sure you add `??external=react,react-dom` at the end of the url, so that your esm bundle doesn't include its own
If you use https://esh.sh, make sure to add `?external=react,react-dom` at the end of the url, so that your esm bundle doesn't include its own
ReactJS version, but uses the one provided with ipyreact.

If you make your own bundle using esbuild, make sure to add the `--external:react --external:react-dom` flags on the CLI.