{"id":13773925,"url":"https://github.com/pmndrs/react-three-offscreen","last_synced_at":"2025-05-15T01:06:54.145Z","repository":{"id":153853448,"uuid":"630864556","full_name":"pmndrs/react-three-offscreen","owner":"pmndrs","description":"📺 Offscreen worker canvas for react-three-fiber","archived":false,"fork":false,"pushed_at":"2025-01-30T08:45:44.000Z","size":4149,"stargazers_count":488,"open_issues_count":15,"forks_count":21,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-08T19:27:01.812Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://offscreen.pmnd.rs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pmndrs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-04-21T10:26:13.000Z","updated_at":"2025-04-07T20:33:26.000Z","dependencies_parsed_at":"2024-01-13T11:57:56.116Z","dependency_job_id":"fef88f26-befb-4d68-ba2d-a2b82ad76ec6","html_url":"https://github.com/pmndrs/react-three-offscreen","commit_stats":{"total_commits":71,"total_committers":4,"mean_commits":17.75,"dds":0.05633802816901412,"last_synced_commit":"076a8f63b864f0f075c3bdf9520481096d8d5184"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmndrs%2Freact-three-offscreen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmndrs%2Freact-three-offscreen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmndrs%2Freact-three-offscreen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmndrs%2Freact-three-offscreen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pmndrs","download_url":"https://codeload.github.com/pmndrs/react-three-offscreen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253878574,"owners_count":21977833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T17:01:21.835Z","updated_at":"2025-05-15T01:06:54.108Z","avatar_url":"https://github.com/pmndrs.png","language":"TypeScript","funding_links":["https://opencollective.com/react-three-fiber"],"categories":["Graphics","TypeScript"],"sub_categories":["Optimization"],"readme":"\u003ch1\u003ereact-three-offscreen\u003c/h1\u003e\n\n[![Version](https://img.shields.io/npm/v/@react-three/offscreen?style=flat\u0026colorA=000000\u0026colorB=000000)](https://npmjs.com/package/@react-three/offscreen)\n[![Downloads](https://img.shields.io/npm/dt/@react-three/offscreen.svg?style=flat\u0026colorA=000000\u0026colorB=000000)](https://npmjs.com/package/@react-three/offscreen)\n[![Twitter](https://img.shields.io/twitter/follow/pmndrs?label=%40pmndrs\u0026style=flat\u0026colorA=000000\u0026colorB=000000\u0026logo=twitter\u0026logoColor=000000)](https://twitter.com/pmndrs)\n[![Discord](https://img.shields.io/discord/740090768164651008?style=flat\u0026colorA=000000\u0026colorB=000000\u0026label=discord\u0026logo=discord\u0026logoColor=000000)](https://discord.gg/ZZjjNvJ)\n[![Open Collective](https://img.shields.io/opencollective/all/react-three-fiber?style=flat\u0026colorA=000000\u0026colorB=000000)](https://opencollective.com/react-three-fiber)\n[![ETH](https://img.shields.io/badge/ETH-f5f5f5?style=flat\u0026colorA=000000\u0026colorB=000000)](https://blockchain.com/eth/address/0x6E3f79Ea1d0dcedeb33D3fC6c34d2B1f156F2682)\n[![BTC](https://img.shields.io/badge/BTC-f5f5f5?style=flat\u0026colorA=000000\u0026colorB=000000)](https://blockchain.com/btc/address/36fuguTPxGCNnYZSRdgdh6Ea94brCAjMbH)\n\n\u003cbr /\u003e\n\u003ca href=\"https://offscreen.pmnd.rs/\"\u003e\u003cimg src=\"/front.jpg\" width=\"100%\" /\u003e\u003c/a\u003e\n\u003cbr /\u003e\n\n```bash\nnpm install three @react-three/fiber @react-three/offscreen\n```\n\nThis is an experimental package that allows you to render your [react-three-fiber](https://github.com/pmndrs/react-three-fiber) scene with an offscreen canvas in a web worker. This is mostly useful for self-contained webgl apps, and un-blocking the main thread.\n\n## What's the big deal, workers existed before\n\nYou only could never just run your existing WebGL/Threejs app in it. It had to be rewritten. Pointer-events wouldn't work, controls, textures, GLTFs, etc. Worse, thanks to Safari you needed to maintain two forks of your app, one that runs in a worker and one that runs on the main thread as a fallback. This is probably the main reason why Threejs with an offscreen canvas has never caught on.\n\nThis package tries to fix that! The goal is that your existing code will just work. It will forward DOM events to the worker, patch and shim Threejs as well as basic document/window interfaces. It will automatically fall back to main thread if a browser doesn't support offscreen canvas. Even the eco system will work (Drei, Rapier physics, Postprocessing, ...).\n\n## Usage\n\nInstead of importing `\u003cCanvas\u003e` from `@react-three/fiber` you can import it from `@react-three/offscreen` and pass a `worker` prop. The `fallback` prop is optional, your scene will be rendered on the main thread when OffscreenCanvas is not supported.\n\nIt takes all other props that `\u003cCanvas\u003e` takes (dpr, shadows, etc), you can use it as a drop-in replacement.\n\n```jsx\n// App.jsx (main thread)\nimport { lazy } from 'react'\nimport { Canvas } from '@react-three/offscreen'\n\n// This is the fallback component that will be rendered on the main thread\n// This will happen on systems where OffscreenCanvas is not supported\nconst Scene = lazy(() =\u003e import('./Scene'))\n\n// This is the worker thread that will render the scene\nconst worker = new Worker(new URL('./worker.jsx', import.meta.url), { type: 'module' })\n\nexport default function App() {\n  return (\n    \u003cCanvas\n      worker={worker} fallback={\u003cScene /\u003e}\n      shadows camera={{ position: [0, 5, 10], fov: 25 }} /\u003e\n  )\n}\n```\n\nYour worker thread will be responsible for rendering the scene. The `render` function takes a single argument, a ReactNode. React-three-fiber and its React-root/reconciler will run in that worker, rendering your contents.\n\n```jsx\n// worker.jsx (worker thread)\nimport { render } from '@react-three/offscreen'\nimport Scene from './Scene'\n\nrender(\u003cScene /\u003e)\n```\n\nYour app or scene should idealy be self contained, it shouldn't postMessage with the DOM. This is because offscreen canvas + webgl is still not supported in Safari. If you must communicate with the DOM, you can use the web broadcast API.\n\n```jsx\n// Scene.jsx (a self contained webgl app)\nexport default function App() {\n  return (\n    \u003cmesh\u003e\n      \u003cboxGeometry /\u003e\n    \u003c/mesh\u003e\n  )\n}\n```\n\n## Troubleshooting\n\n### Compromises and defaults\n\nFor better interop all non-passive events (click, contextmenu, dlbclick) will preventDefault, pointerdown will capture, pointerup will release capture.\n\n### Nextjs\n\nJust make sure to disable SSR for the canvas component because `Worker` only exists in the DOM:\n\n```jsx\n// src/app/page.jsx\nimport dynamic from 'next/dynamic'\n\nconst App = dynamic(() =\u003e import('@/components/App'), { ssr: false })\n```\n\n### Vite\n\nVites `@vitejs/plugin-react` tries to inject styles into `document` and assumes the presence of `window`, neither exist in a worker. As such you can consider the official React plugin faulty, it won't run React in a web worker. The workaround:\n\n1. yarn add @vitejs/plugin-react@3.1.0\n2. disable fast refresh (see: [stackoverflow](https://stackoverflow.com/questions/73815639/how-to-use-jsx-in-a-web-worker-with-vite)) (the option was removed in 4.x)\n\n```jsx\nexport default defineConfig({\n  plugins: [react({ fastRefresh: false })],\n  worker: { plugins: [react()] },\n})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmndrs%2Freact-three-offscreen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpmndrs%2Freact-three-offscreen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmndrs%2Freact-three-offscreen/lists"}