Docs/add guides section with getting started

docs/docs/components/_category_.yml

@@ -0,0 +1,4 @@
+label: Components
+position: 1
+collapsed: true
+collapsible: true

docs/docs/extend.mdx → docs/docs/extend/extend.mdx

@@ -1,5 +1,7 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
+title: Extend
+description: Learn how to extend @pixi/react with custom PixiJS components and use the extend API to keep your bundle size small.
 ---
 
 One of the most important concepts to understand with v8 is `extend`. Normally `@pixi/react` would have to import all of Pixi.js to be able to provide the full library as JSX components. Instead, we use an internal catalogue of components populated by the `extend` API. This allows you to define exactly which parts of Pixi.js you want to import, keeping your bundle sizes small.

docs/docs/getting-started/_category_.yml

@@ -0,0 +1,4 @@
+label: Getting Started
+position: 0
+collapsed: false
+collapsible: true

docs/docs/getting-started/ecosystem.mdx

@@ -0,0 +1,274 @@
+---
+sidebar_position: 2
+title: Ecosystem
+description: Explore the @pixi/react ecosystem, including React-specific tools, PixiJS integration, and community resources.
+---
+
+`@pixi/react` is designed to work seamlessly with both the React and PixiJS ecosystems. This integration allows you to leverage the best tools and libraries from both worlds to create powerful, interactive applications.
+
+## React Integration
+
+### React DevTools
+
+Since `@pixi/react` components are real React components, you can use [React DevTools](https://react.dev/learn/react-developer-tools) to inspect component hierarchies, props, and state just like any other React application.
+
+### State Management
+
+Use any React state management solution with `@pixi/react`:
+
+#### Redux Toolkit
+
+```jsx
+import { useSelector, useDispatch } from 'react-redux'
+import { Application, extend } from '@pixi/react'
+import { Sprite } from 'pixi.js'
+
+extend({ Sprite })
+
+function GameSprite() {
+  const player = useSelector(state => state.player)
+  const dispatch = useDispatch()
+
+  return (
+    <Application>
+      <pixiSprite
+        x={player.x}
+        y={player.y}
+        texture={player.texture}
+        eventMode="static"
+        onclick={() => dispatch(movePlayer())}
+      />
+    </Application>
+  )
+}
+```
+
+#### Zustand
+
+```jsx
+import { usePlayerStore } from './store'
+
+function PlayerSprite() {
+  const { x, y, texture, move } = usePlayerStore()
+
+  return (
+    <pixiSprite
+      x={x}
+      y={y}
+      texture={texture}
+      eventMode="static"
+      onclick={move}
+    />
+  )
+}
+```
+
+### Custom Hooks
+
+Create reusable game logic with React hooks:
+
+```jsx
+import { useTick } from '@pixi/react'
+import { useCallback, useMemo } from 'react'
+
+function useGameLoop(callback, enabled = true) {
+  const memoizedCallback = useCallback(callback, [callback])
+
+  useTick(memoizedCallback, { isEnabled: enabled })
+}
+
+function useCollision(sprite1, sprite2) {
+  return useMemo(() => {
+    // collision detection logic
+    return checkCollision(sprite1, sprite2)
+  }, [sprite1, sprite2])
+}
+```
+
+### Context Providers
+
+Share game state across components:
+
+```jsx
+import { createContext, useState } from 'react'
+import { Application } from '@pixi/react'
+
+const GameContext = createContext()
+
+function GameProvider({ children }) {
+  const [gameState, setGameState] = useState(initialState)
+
+  return (
+    <GameContext.Provider value={{ gameState, setGameState }}>
+      <Application>
+        {children}
+      </Application>
+    </GameContext.Provider>
+  )
+}
+```
+
+---
+
+## PixiJS Integration
+
+Since `@pixi/react` is a thin wrapper around PixiJS, you can use any PixiJS features directly:
+
+### Filters
+
+Apply visual effects using PixiJS filters:
+
+```jsx
+import { BlurFilter } from 'pixi.js'
+import { useMemo } from 'react'
+
+function FilteredSprite() {
+  const filters = useMemo(() => [
+    new BlurFilter(4)
+  ], [])
+
+  return (
+    <pixiSprite
+      texture="hero.png"
+      filters={filters}
+    />
+  )
+}
+```
+
+### Custom Components with Third-Party Libraries
+
+Use the `extend` API to integrate third-party PixiJS libraries:
+
+#### [pixi-viewport](https://github.com/davidfig/pixi-viewport)
+
+Create interactive, zoomable viewports:
+
+```jsx
+import { extend } from '@pixi/react'
+import { Viewport } from 'pixi-viewport'
+
+extend({ Viewport })
+
+function GameViewport() {
+  return (
+    <pixiViewport
+      screenWidth={800}
+      screenHeight={600}
+      worldWidth={1600}
+      worldHeight={1200}
+    >
+      <pixiContainer>
+        {/* Your game objects */}
+      </pixiContainer>
+    </pixiViewport>
+  )
+}
+```
+
+> **Note**: Third-party libraries compatibility may vary. Always test thoroughly and check library documentation for PixiJS v8 compatibility.
+
+---
+
+## Development Tools
+
+### TypeScript Support
+
+`@pixi/react` provides full TypeScript support. For custom components, extend the type definitions:
+
+```typescript
+// global.d.ts
+import { PixiReactElementProps } from '@pixi/react'
+import { Viewport } from 'pixi-viewport'
+
+declare module '@pixi/react' {
+  interface PixiElements {
+    viewport: PixiReactElementProps<typeof Viewport>
+  }
+}
+```
+
+### Testing
+
+Test your `@pixi/react` components with [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/):
+
+```jsx
+import { render } from '@testing-library/react'
+import { Application } from '@pixi/react'
+import MyGameComponent from './MyGameComponent'
+
+test('renders game component', () => {
+  render(
+    <Application>
+      <MyGameComponent />
+    </Application>
+  )
+  // Test your component logic
+})
+```
+
+### Storybook
+
+Document your graphics components with [Storybook](https://storybook.js.org/):
+
+```jsx
+export default {
+  title: 'Game/PlayerSprite',
+  component: PlayerSprite,
+}
+
+export const Default = () => (
+  <Application>
+    <PlayerSprite x={100} y={100} />
+  </Application>
+)
+```
+
+---
+
+## React Framework Integration
+
+### Next.js
+
+`@pixi/react` works seamlessly with Next.js. For server-side rendering, make sure to import PixiJS components dynamically:
+
+```jsx
+import dynamic from 'next/dynamic'
+
+const GameComponent = dynamic(
+  () => import('../components/GameComponent'),
+  { ssr: false }
+)
+
+export default function GamePage() {
+  return <GameComponent />
+}
+```
+
+### Create React App
+
+`@pixi/react` works out of the box with Create React App. Just install the dependencies and start building:
+
+```bash
+npm install pixi.js@^8.2.6 @pixi/react
+```
+
+### Vite
+
+Perfect compatibility with Vite's fast development experience:
+
+```bash
+npm create vite@latest my-pixi-app -- --template react
+npm install pixi.js@^8.2.6 @pixi/react
+```
+
+---
+
+## Community Resources
+
+- **[GitHub Repository](https://github.com/pixijs/pixi-react)** - Source code, issues, and discussions
+- **[GitHub Discussions](https://github.com/pixijs/pixi-react/discussions)** - Ask questions and share ideas
+- **[PixiJS Discord](https://discord.gg/QrnxmQUPGV)** - Get help from the community
+- **[Examples](https://github.com/pixijs/pixi-react/tree/main/docs/src/examples)** - Browse code examples
+
+The combination of React's declarative component model with PixiJS's high-performance rendering provides everything you need to build incredible interactive experiences.

docs/docs/getting-started/intro.mdx

@@ -0,0 +1,97 @@
+---
+title: Introduction
+sidebar_position: 0
+hide_title: true
+description: Overview of @pixi/react, its features, and what makes it the best way to write PixiJS applications in React.
+---
+
+<div align="center" style={{ paddingTop: '20px' }}>
+   <img src="/img/logo-main.svg" alt="Logo" width={'100%'} style={{ maxHeight: 150 }} />
+</div>
+<br />
+<div
+  align="center"
+  style={{ display: 'flex', flexDirection: 'row', alignItems: 'center', justifyContent: 'center', gap: 8 }}
+>
+  <a href="https://github.com/pixijs/pixi-react/releases">
+    <img src="https://img.shields.io/github/v/release/pixijs/pixi-react" alt="release" />
+  </a>
+  <a href="https://npmjs.com/package/@pixi/react">
+    <img src="https://img.shields.io/npm/dm/@pixi/react" alt="downloads" />
+  </a>
+  <a href="https://github.com/pixijs/pixi-react/actions">
+    <img src="https://img.shields.io/circleci/project/github/pixijs/pixi-react/master.svg" alt="ci tests" />
+  </a>
+  <a href="https://github.com/pixijs/pixi-react/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="license" />
+  </a>
+  <a href="https://discord.gg/QrnxmQUPGV">
+    <img src="https://img.shields.io/badge/chat-discord-blue?style=flat&logo=discord" alt="discord chat" />
+  </a>
+</div>
+
+<div align="center" style={{ marginTop: '20px' }}>
+  <strong>Simply the best way to write PixiJS applications in React</strong>
+  <br />
+  <sub>
+    Write <a href="http://www.pixijs.com/">PixiJS</a> applications using React declarative style 👌
+  </sub>
+</div>
+
+## Features ⚡️
+
+> `@pixi/react` is an open-source, production-ready library to render high performant PixiJS applications in React.
+
+- ⚛️ **React v19 Support** - Built for the latest React features
+- 🏎️ **PixiJS v8 Compatible** - Latest PixiJS performance and features
+- 📦 **Tree-shakeable** - Only import what you need with the `extend` API
+- 🎯 **Type-safe** - Full TypeScript support with intelligent autocomplete
+- � **Declarative** - Write PixiJS code using familiar React patterns
+- 🪝 **React Hooks** - Built-in hooks for animations, tickers, and more
+- � **No Overhead** - Components render outside of React for maximum performance
+- 🛠️ **Extensible** - Easy integration with custom PixiJS components
+
+## What Is @pixi/react?
+
+`@pixi/react` is an open-source, production-ready library to render high performant PixiJS applications in React. It provides a declarative way to build high-performance 2D graphics and interactive experiences using familiar React patterns.
+
+Write [PixiJS](http://www.pixijs.com/) applications using React declarative style and harness the power of PixiJS within React's paradigm. By combining PixiJS's rendering capabilities with React's component model, you can create stunning visual applications while maintaining clean, maintainable code.
+
+## What Makes @pixi/react Special
+
+At its core, `@pixi/react` offers:
+
+- **Declarative Rendering**: Write PixiJS applications using JSX, making complex scenes easy to understand and maintain.
+- **React Integration**: Seamless integration with React's lifecycle, hooks, and state management.
+- **Performance Focused**: Components render outside of React's reconciliation loop for maximum performance.
+- **Tree Shaking**: Import only the PixiJS components you need using the `extend` API.
+- **Type Safety**: Full TypeScript support with intelligent autocomplete for all PixiJS properties.
+
+## Why Choose @pixi/react?
+
+`@pixi/react` bridges the gap between PixiJS's performance and React's developer experience. You get:
+
+- **Familiar Patterns**: Use React concepts like props, state, and hooks to control PixiJS objects.
+- **Component Reusability**: Create reusable graphics components that can be shared across projects.
+- **Developer Experience**: Benefit from React DevTools, hot reloading, and the entire React ecosystem.
+- **No Compromises**: Everything that works in PixiJS works in `@pixi/react` without limitations.
+
+## Who Is @pixi/react For?
+
+`@pixi/react` is perfect for React developers who want to:
+
+- Build interactive games and animations within React applications
+- Create data visualizations with complex graphics and animations
+- Develop creative web experiences without leaving the React ecosystem
+- Migrate existing PixiJS applications to a more maintainable React architecture
+- Learn PixiJS while leveraging existing React knowledge
+
+## Does it have limitations?
+
+None. Everything that works in PixiJS will work here without exception.
+
+## Get Started
+
+Ready to dive in? Check out our [Quick Start](/getting-started/quick-start) guide to create your first `@pixi/react` application!
+
+PixiJS is more than just a rendering engine; it’s a gateway to creative freedom. Dive into our comprehensive [documentation](./quick-start.mdx) or join the [community](https://discord.gg/CPTjeb28nH) to start your journey with PixiJS today.