@threlte/preprocess

preprocessThrelte

Threlte provides a custom preprocessor that automagically turns <T.Mesh> into <Three type={Mesh} />. It resolves dependencies and automatically places imports for the corresponding modules used throughout your component. By default, you can use any import from 'three'. The preprocessor is extendable, so that other modules (such as those from the famous "examples" directory) can be used.

It's best described with a basic example. The preprocessor will turn this:

<script lang="ts">
	import { T } from '@threlte/core'
</script>

<T.Mesh>
	<T.BoxGeometry />
	<T.MeshStandardMaterial />
</T.Mesh>

into this:

<script lang="ts">
	import { Three } from '@threlte/core'
	import { Mesh, BoxGeometry, MeshStandardMaterial } from 'three'
</script>

<Three type={Mesh}>
	<Three type={BoxGeometry} />
	<Three type={MeshStandardMaterial} />
</Three>

# Installation

1. Install the package @threlte/preprocess

npm install -D @threlte/preprocess

2. Install additional dependencies

If you need to run any other preprocessors in your project (e.g. svelte-preprocess), you also need to install svelte-sequential-preprocessor in order to run the preprocessors sequentially. This step is mandatory for a default SvelteKit project. In this case threltes preprocessor must succeed any other preprocessor.

npm install -D svelte-sequential-preprocessor

3. Adapt your svelte configuration

• As the only preprocessor

import { preprocessThrelte } from '@threlte/preprocess'

const config = {
	preprocess: preprocessThrelte()
}

• In conjunction with other preprocessors

import sequence from 'svelte-sequential-preprocessor'
import preprocess from 'svelte-preprocess'
import { preprocessThrelte } from '@threlte/preprocess'

const config = {
	preprocess: sequence([preprocess(), preprocessThrelte()])
}

# Configuration

By default, the preprocessor is able to use all exports of three. This means that if you were to import a module via import { BoxGeometry } from 'three' it's automatically in the default catalogue. You can however extend that catalogue with the option extensions which is an object where the key is a module name and the value is an array of import names:

import { preprocessThrelte } from '@threlte/preprocess'

const config = {
	preprocess: preprocessThrelte({
		extensions: {
			// import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls'
			'three/examples/jsm/controls/OrbitControls': ['OrbitControls'],

			// import { TransformControls } from 'three/examples/jsm/controls/TransformControls'
			'three/examples/jsm/controls/TransformControls': ['TransformControls'],

			// import { CustomGrid } from '$lib/CustomGrid'
			'$lib/CustomGrid': ['CustomGrid']
		}
	})
}