use tree-shaking to reduce the bundle size by >90%

[samuelstroschein]

Problem

Typebox ships too large bundle sizes for resource constraint environments. Aka typebox can't be used.

The following code ships 36.3kb [source]

 import { Type, type Static } from "@sinclair/typebox"

export type Settings = Static<typeof Settings>
export const Settings = Type.Object({
	storagePath: Type.String(),
})

Proposal

Leverage ESM tree-shaking to decrease bundle sizes by over 90%.

For comparison, valibot, which leverages tree-shaking, bundles 703 bytes for the same code [source]. A bundle size reduction of 98% compared to typebox.

Examples

The following code would only import Object and String validators without all available Type.* stuff.

import { Object, String, type Static } from "@sinclair/typebox"

export type Settings = Static<typeof Settings>
export const Settings = Object({
	storagePath: String(),
})

The syntax of Type.* could even be sustained with namespace imports which are tree-shaken by bundlers too.

import * as Type from "@sinclair/typebox"

export type Settings = Static<typeof Settings>
export const Settings = Type.Object({
	storagePath: Type.String(),
})

Additional information

The Value import of typebox is too large as well, counting >70kb that are included in the bundle size. Valibot's equivalent parse bundles only 100 bytes.

[sinclairzx81]

@samuelstroschein Hiya,

---

Bundle Sizes

Just for reference, the following table are the current bundling sizes for various libraries.

Type System	Minified	GZipped	Reference
TypeBox	34.3kB	8.3kB	0.31.17
Valibot	35.5kB	6.6kB	0.18.0
Zod	57.0kB	13.2kB	3.22.2
Ajv	119.6kB	35.2kB	8.12.0
HyperJump	44.3kB	11.6kB	1.6.1
ArkType	67.7kB	18.9kB	1.0.21-alpha

Note that the TypeBox result above relates specifically to the TypeBuilder (which is currently non-shakable).

---

ESM Modules

The TypeBox TypeBuilder (everything inside typebox.ts) is long overdue for a module split. This module has been prepared for splitting over the past several iterations of the library, but currently pending "the split" until things are closer to 1.0.

The anticipated import scheme post split will be:

import Type, { Static } from '@sinclair/typebox'

Given this is a breaking change, there is some reluctance to enact this change until everything is finalized for 1.0 (and that this scheme will be supported into the future). So this is planned for, just not for a while.

Value Modules

The Value import of typebox is too large as well, counting >70kb that are included in the bundle size. Valibot's equivalent parse bundles only 100 bytes.

You won't get to 100 bytes, but you can significantly reduce the size of the Value modules by importing each function individually.

import { Check } from '@sinclair/typebox/value/check' // > 24 kb

Note: TypeBox does need to import logic to check for all types (as it can't know in advance what types are going to passed to it). Work was done on the 0.30.x and 0.31.x revisions to reduce output size (many code level optimizations), as well as to make each function with it's associated infrastructure individually importable.

Outside of the above, there is very little else that can be done while keeping schematics and validation logic separated (which is a key design principle for the library). However, there may be room to explore more optimal (bundler friendly) Json Schema validation libraries external to TypeBox.

It would be interesting to see just how minimal a Json Schema implementation could get.

Hope this brings some insight
Cheers
S

[sinclairzx81]

@samuelstroschein Hiya,

I would expect something like the following (with the default export and type functions would be statically analyzable by bundle optimizers)

import Type from 'typebox'
// or ...
import { String, Object } from 'typebox'

The bundle sizes of libraries are irrelevant if tree-shakable. As it stands right now, importing Type leads to 36.3kb that are bundled. I fear that the bundling size with the import schema your propose will make no significant differences as all Type annotations are still bundled.

Keep in mind, individual imports (i.e. as per Valibot) are actually not a big priority for TypeBox, rather the main motivation is to adopt ESM (in whatever capacity) and ensure bundlers have enough to statically analyze (and optimize) the bundle.

In this regard, I feel the default export is generally how people would prefer to consume TypeBox under ESM (vs the barrel import) as the default narrows the import scope to only Type.*. Additional infrastructure (including the Types themselves) can be imported via { ... } which I would expect a capable bundle optimizer to understand no default import was used (so can be omitted from the output bundle)

This is the reasoning anyway. It could use some testing under popular optimizers.

[samuelstroschein]

I am implementing a tree-shakable i18n library. My tests with rollup/vite yielded the following result:

// not tree-shakable 
import Type from 'typebox'

// tree-shakable
import { String, Object } from 'typebox'

// syntactic sugar of the tree-shakable version is a namespace import
// bundlers ignore the syntactic sugar and treat the following import as 
// import { Object } from "typebox"
import * as Type from "typebox"
Type.Object()

Under any circumstance, importing { Type } or Type as default import will lead to (too) large bundle sizes. To avoid a breaking change, you can keep import { Type } but deprecate Type, expose import { Object, String } and mention in the docs that a namespace import can be used import * as Type for a nicer DX.

[samuelstroschein]

I am pressing the issue because typebox is too large for inlang plugins where a plugin has a size of <10kb. Using typebox in its current form would add 36kb to each plugin. A no go. Hence, we had to switch to valibot for plugins.

[sinclairzx81]

@samuelstroschein Heya,

The following would be ok though right?

// not tree-shakable 
import Type from 'typebox'

// tree-shakable
import { String, Object } from 'typebox'

// presumed also tree-shakable
import * as Type from 'typebox'

I am pressing the issue because typebox is too large for inlang plugins where a plugin has a size of <10kb. Using typebox in its current form would add 36kb to each plugin. A no go. Hence, we had to switch to valibot for plugins.

Inlang looks like a cool project btw. And yeah, that's a bit unfortunate about the plugin size constraints. The TypeBuilder currently gzip's down to around 8kb with everything in there (assuming you don't need validators). With validators, the minimum you would be looking at around 24kb. Even with TB opting for barrel imports, you're still going to be looking at 20-30kb for validators and additional TB components.

I'm not very keen to deprecate Type.* (as I feel this actually improves DX as it narrows specifically to constructible types vs the other infrastructure used for type composition). Explicit imports of types via { String, Object } will most likely be supported via ESM and permit developers to optimize if they need that. I feel this strikes a good balance between something like Zod (not tree shakeable) and Valibot (by being optionally tree shakeable) while still remaining distinctly "TypeBox" (as well as not relying too much on the capabilities of JS optimizers)

But let me give it some thought. ESM work is still a fair way off (I have some prototypes I need to test against). Also, I wouldn't expect ESM before the end of the year (but will see how the workload is in December). Just keep in mind that implementing any of this will be significant breaking API change, so do want to have good justification and rationales in place before going ahead with anything. It's a bit of a balancing act (and there are other trade-offs to consider), but should deprecation of Type.* be desirable (when contrasted with other functionality), I'll give it a review when I get around to the work.

Let's keep this thread active and open for discussion :)

[samuelstroschein]

@sinclairzx81

The following would be ok though right?

// not tree-shakable 
import Type from 'typebox'

// tree-shakable
import { String, Object } from 'typebox'

// presumed also tree-shakable
import * as Type from 'typebox'

I would remove the default import. It seems to me that you can implement tree-shaking in a non-breaking change manner as follows:

// current import schema, still supported
import { Type, Static } from '@sinclair/typebox'

Type.String() // -> warning that `Type` is deprecated in favor of `import * as Type` but it still works!

// new exports of individual types (tree-shakable) 
import { String } from  '@sinclair/typebox'

String()

// syntactic sugar for type 
import * as Type from "@sinclair/typebox"

// really a minor "issue"/non-issue that static now runs under type. 
type X = Type.Static<typeof X>
const X = Type.String()

The code above is non-breaking while encouraging best practices and automatic tree-shaking, making typebox substantially better (and hopefully enabling new use cases for typebox in resource constraint environments). No developer would have to debug "why is typebox shipping 30k+ kb" if you deprecate the direct import of Type and do not expose a default import.