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.

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:

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

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

# 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.