Visit the Documentation of the upcoming Threlte 6.
  1. Getting Started

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 and three – 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.

terminal
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

Adapt svelte.config.js

Add Threlte's preprocessor as well as 'svelte-sequential-preprocessor' to your Svelte config:

svelte.config.js
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

Adapt vite.config.js

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

vite.config.js
const config = {
	// …
	ssr: {
		noExternal: ['three', 'troika-three-text']
	}
}
TIP

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.