# Getting started

To install Deepkit's runtime type system two packages are needed: The Deepkit Type Compiler and the Deepkit Type package itself. The type compiler is a TypeScript transformer that generates runtime type information from TypeScript types. The type package contains the runtime virtual machine and type annotations as well as many useful functions for working with types.


## Installation 

```sh
npm install --save @deepkit/type
npm install --save-dev @deepkit/type-compiler typescript ts-node
```

Runtime type information is not generated by default. It must be set `"reflection": true` in the `tsconfig.json` file to enable it. 

If decorators are to be used, `"experimentalDecorators": true` must be enabled in `tsconfig.json`. This is not strictly necessary to work with `@deepkit/type`, but necessary for certain functions of other Deepkit libraries and in Deepkit Framework.

_File: tsconfig.json_

```json
{
  "compilerOptions": {
    "module": "CommonJS",
    "target": "es6",
    "moduleResolution": "node",
    "experimentalDecorators": true
  },
  "reflection": true
}
```

Write your first code with runtime type information:

_File: app.ts_

```typescript
import { cast, MinLength, ReflectionClass } from '@deepkit/type';

interface User {
    username: string & MinLength<3>;
    birthDate?: Date;
}

const user = cast<User>({
    username: 'Peter',
    birthDate: '2010-10-10T00:00:00Z'
});
console.log(user);

const reflection = ReflectionClass.from<User>();
console.log(reflection.getProperty('username').type);
```

And run it with `ts-node`:

```sh
./node_modules/.bin/ts-node app.ts
```

## Interactive Example

Here is a codesandbox example: https://codesandbox.io/p/sandbox/deepkit-runtime-types-fjmc2f?file=index.ts

## Type compiler

TypeScript itself does not allow to configure the type compiler via a `tsconfig.json`. It is necessary to either use the TypeScript compiler API directly or a build system like Webpack with _ts-loader_. To save this inconvenient way for Deepkit users, the Deepkit type compiler automatically installs itself in `node_modules/typescript` once `@deepkit/type-compiler` is installed (this is done via NPM install hooks).
This makes it possible for all build tools that access the locally installed TypeScript (the one in `node_modules/typescript`) to automatically have the type compiler enabled. This makes _tsc_, Angular, webpack, _ts-node_, and some other tools automatically work with the deepkit type compiler.

If the type compiler could not be successfully installed automatically (for example because NPM install hooks are disabled), this can be done manually with the following command:

```sh
node_modules/.bin/deepkit-type-install
```

Note that `deepkit-type-install` must be run if the local typescript version has been updated (for example, if the typescript version in package.json has changed and `npm install` is run).

## Webpack

If you want to use the type compiler in a webpack build, you can do so with the `ts-loader` package (or any other typescript loader that supports transformer registration).

_File: webpack.config.js_

```javascript
const typeCompiler = require('@deepkit/type-compiler');

module.exports = {
  entry: './app.ts',
  module: {
    rules: [
      {
        test: /\.tsx?$/,
          use: {
            loader: 'ts-loader',
            options: {
              //this enables @deepkit/type's type compiler
              getCustomTransformers: (program, getProgram) => ({
                before: [typeCompiler.transformer],
                afterDeclarations: [typeCompiler.declarationTransformer],
              }),
            }
          },
          exclude: /node_modules/,
       },
    ],
  },
}
```