Getting Started
Installation
Threlte consists of 4 packages which can be installed and used individually. @threlte/core
and three
are required for all projects while the other packages are optional.
@threlte/core
andthree
– required
three.js and core the library are required. Compose three.js scenes declaratively and state-driven.
@threlte/preprocess
Threlte's preprocessor provides auto-importing and an improved developer experience.
svelte-sequential-preprocessor
– external package
svelte-sequential-preprocessor is an external package and is required if you need to run other preprocessors as well.
@threlte/extras
Components, helpers, hooks and more that extend the core functionality.
@threlte/rapier
Components and hooks to use the Rapier physics engine in Threlte.
@threlte/theatre
Components and hooks to use the animation library Theatre.js in Threlte.
@types/three
– external package
TypeScript types for three.js.
Choose the packages you want to use
The rest of this guide will adapt.
Install the packages with npm
, pnpm
, yarn
or any other package manager you prefer.
npm i -D three @threlte/core @threlte/preprocess svelte-sequential-preprocessor @threlte/extras @threlte/rapier @dimforge/rapier3d-compat @threlte/theatre @theatre/core @theatre/studio @types/three
Configuration
svelte.config.js
Adapt Add Threlte's preprocessor as well as 'svelte-sequential-preprocessor'
to your Svelte config:
import preprocess from 'svelte-preprocess'
import seqPreprocessor from 'svelte-sequential-preprocessor'
import { preprocessThrelte } from '@threlte/preprocess'
const config = {
// …
preprocess: seqPreprocessor([preprocess(), preprocessThrelte()])
}
export default config
vite.config.js
Adapt If you are using Threlte with SvelteKit, adapt your Vite configuration to prevent three
and troika-three-text
from being externalized for SSR by vites externalization step
const config = {
// …
ssr: {
noExternal: ['three', 'troika-three-text']
}
}
See this comment for tips on how to reduce bundle size when working with bundlers like vite and three.js.
First Scene
Build your first scene:
<script>
import { Canvas, InteractiveObject, OrbitControls, T } from '@threlte/core'
import { spring } from 'svelte/motion'
import { degToRad } from 'three/src/math/MathUtils'
const scale = spring(1)
</script>
<div>
<Canvas>
<T.PerspectiveCamera makeDefault position={[10, 10, 10]} fov={24}>
<OrbitControls maxPolarAngle={degToRad(80)} enableZoom={false} target={{ y: 0.5 }} />
</T.PerspectiveCamera>
<T.DirectionalLight castShadow position={[3, 10, 10]} />
<T.DirectionalLight position={[-3, 10, -10]} intensity={0.2} />
<T.AmbientLight intensity={0.2} />
<!-- Cube -->
<T.Group scale={$scale}>
<T.Mesh position.y={0.5} castShadow let:ref>
<!-- Add interaction -->
<InteractiveObject
object={ref}
interactive
on:pointerenter={() => ($scale = 2)}
on:pointerleave={() => ($scale = 1)}
/>
<T.BoxGeometry />
<T.MeshStandardMaterial color="#333333" />
</T.Mesh>
</T.Group>
<!-- Floor -->
<T.Mesh receiveShadow rotation.x={degToRad(-90)}>
<T.CircleGeometry args={[3, 72]} />
<T.MeshStandardMaterial color="white" />
</T.Mesh>
</Canvas>
</div>
<style>
div {
height: 100%;
width: 100%;
}
</style>
It should look something like this:
Congratulations 🎉 Orbit around the cube, hover over, head over to the Playground and change some values.