ddb7585057
* feat: add docs for getCommonBounds * docs: add docs for frames api support * docs: update docs for regenerateIds opts in convertToExcalidrawElements * add docs for ref removal * add docs for lock support and insertOnCanvasDirectly in setActiveTool * fix broken links * update docs for next js support * update docs for Preact * add faq * docs: add `onChange`, `onPointerDown`, `onPointerUp` docs * docs: update `useDevice` docs * update docs for disabling image tool * add docs for withinBounds helpers * fix lint * upgrade excal * add docusaurus2-dotenv for expose env vars * fix env variable and upgrade excal * Update dev-docs/docs/@excalidraw/excalidraw/api/excalidraw-element-skeleton.mdx Co-authored-by: David Luzar <5153846+dwelle@users.noreply.github.com> * update docs Co-authored-by: David Luzar <5153846+dwelle@users.noreply.github.com> * update docs for process.env --------- Co-authored-by: dwelle <5153846+dwelle@users.noreply.github.com>
181 lines
4.7 KiB
Plaintext
181 lines
4.7 KiB
Plaintext
# Integration
|
|
|
|
## Module bundler
|
|
|
|
If you are using a module bundler (for instance, Webpack), you can import it as an ES6 module as shown below
|
|
|
|
```js
|
|
import { Excalidraw } from "@excalidraw/excalidraw";
|
|
```
|
|
|
|
:::info
|
|
|
|
Throughout the documentation we use live, editable Excalidraw examples like the one shown below.
|
|
|
|
While we aim for the examples to closely reflect what you'd get if you rendered it yourself, we actually initialize it with some props behind the scenes.
|
|
For example, we're passing a `theme` prop to it based on the current color theme of the docs you're just reading.
|
|
|
|
:::
|
|
|
|
```jsx live
|
|
function App() {
|
|
return (
|
|
<>
|
|
<h1 style={{ textAlign: "center" }}>Excalidraw Example</h1>
|
|
<div style={{ height: "500px" }}>
|
|
<Excalidraw />
|
|
</div>
|
|
</>
|
|
);
|
|
}
|
|
```
|
|
|
|
### Next.js
|
|
|
|
Since _Excalidraw_ doesn't support server side rendering, you should render the component once the host is `mounted`.
|
|
|
|
Here are two ways on how you can render **Excalidraw** on **Next.js**.
|
|
|
|
|
|
|
|
1. Using **Next.js Dynamic** import [Recommended].
|
|
|
|
Since Excalidraw doesn't support server side rendering so you can also use `dynamic import` to render by setting `ssr` to `false`.
|
|
|
|
```jsx showLineNumbers
|
|
import dynamic from "next/dynamic";
|
|
const Excalidraw = dynamic(
|
|
async () => (await import("@excalidraw/excalidraw")).Excalidraw,
|
|
{
|
|
ssr: false,
|
|
},
|
|
);
|
|
export default function App() {
|
|
return <Excalidraw />;
|
|
}
|
|
```
|
|
|
|
Here is a working [demo](https://codesandbox.io/p/sandbox/excalidraw-with-next-dynamic-k8yjq2).
|
|
|
|
|
|
2. Importing Excalidraw once **client** is rendered.
|
|
|
|
```jsx showLineNumbers
|
|
import { useState, useEffect } from "react";
|
|
export default function App() {
|
|
const [Excalidraw, setExcalidraw] = useState(null);
|
|
useEffect(() => {
|
|
import("@excalidraw/excalidraw").then((comp) =>
|
|
setExcalidraw(comp.Excalidraw),
|
|
);
|
|
}, []);
|
|
return <>{Excalidraw && <Excalidraw />}</>;
|
|
}
|
|
```
|
|
|
|
Here is a working [demo](https://codesandbox.io/p/sandbox/excalidraw-with-next-5xb3d)
|
|
|
|
The `types` are available at `@excalidraw/excalidraw/types`, you can view [example for typescript](https://codesandbox.io/s/excalidraw-types-9h2dm)
|
|
|
|
### Preact
|
|
|
|
Since we support `umd` build ships with `react/jsx-runtime` and `react-dom/client` inlined with the package. This conflicts with `Preact` and hence the build doesn't work directly with `Preact`.
|
|
|
|
However we have shipped a separate build for `Preact` so if you are using `Preact` you need to set `process.env.IS_PREACT` to `true` to use the `Preact` build.
|
|
|
|
Once the above `env` variable is set, you will be able to use the package in `Preact` as well.
|
|
|
|
:::info
|
|
|
|
When using `vite` or any build tools, you will have to make sure the `process` is accessible as we are accessing `process.env.IS_PREACT` to decide whether to use `preact` build.
|
|
|
|
Since Vite removes env variables by default, you can update the vite config to ensure its available :point_down:
|
|
|
|
```
|
|
define: {
|
|
"process.env.IS_PREACT": process.env.IS_PREACT,
|
|
},
|
|
```
|
|
:::
|
|
|
|
## Browser
|
|
|
|
To use it in a browser directly:
|
|
|
|
For development use :point_down:
|
|
|
|
```js
|
|
<script
|
|
type="text/javascript"
|
|
src="https://unpkg.com/@excalidraw/excalidraw/dist/excalidraw.development.js"
|
|
></script>
|
|
```
|
|
|
|
For production use :point_down:
|
|
|
|
```js
|
|
<script
|
|
type="text/javascript"
|
|
src="https://unpkg.com/@excalidraw/excalidraw/dist/excalidraw.production.min.js"
|
|
></script>
|
|
```
|
|
|
|
You will need to make sure `react`, `react-dom` is available as shown in the below example. For prod please use the production versions of `react`, `react-dom`.
|
|
|
|
import Tabs from "@theme/Tabs";
|
|
import TabItem from "@theme/TabItem";
|
|
|
|
<Tabs>
|
|
<TabItem value="html" label="html">
|
|
|
|
```html
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<title>Excalidraw in browser</title>
|
|
<meta charset="UTF-8" />
|
|
<script src="https://unpkg.com/react@18.2.0/umd/react.development.js"></script>
|
|
<script src="https://unpkg.com/react-dom@18.2.0/umd/react-dom.development.js"></script>
|
|
|
|
<script
|
|
type="text/javascript"
|
|
src="https://unpkg.com/@excalidraw/excalidraw/dist/excalidraw.development.js"
|
|
></script>
|
|
</head>
|
|
|
|
<body>
|
|
<div class="container">
|
|
<h1>Excalidraw Embed Example</h1>
|
|
<div id="app"></div>
|
|
</div>
|
|
<script type="text/javascript" src="src/index.js"></script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="js" label="Javascript">
|
|
|
|
```js showLineNumbers
|
|
const App = () => {
|
|
return React.createElement(
|
|
React.Fragment,
|
|
null,
|
|
React.createElement(
|
|
"div",
|
|
{
|
|
style: { height: "500px" },
|
|
},
|
|
React.createElement(ExcalidrawLib.Excalidraw),
|
|
),
|
|
);
|
|
};
|
|
|
|
const excalidrawWrapper = document.getElementById("app");
|
|
const root = ReactDOM.createRoot(excalidrawWrapper);
|
|
root.render(React.createElement(App));
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|