# Getting started

Save time by starting your project with our Cli:

npm install -g @tsed/cli
tsed init .
1
2

See our CLI website for more details.

Or by using on one of these kits:

# Installation from scratch

You can get the latest version of Ts.ED using the following npm command:

    TIP

    The following modules also are recommended:

      WARNING

      It is really important to keep the same version for all @tsed/* packages. To prevent errors, fix the version for each Ts.ED packages:

      {
        "dependencies": {
          "@tsed/common": "5.56.0",
          "@tsed/di": "5.56.0",
          "@tsed/core": "5.56.0",
          "@tsed/exceptions": "5.56.0",
          "@tsed/plaftorm-express": "5.56.0",
          "@tsed/swagger": "5.56.0"
        }
      } 
      
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10

      WARNING

      Ts.ED requires Node >= 10, Express >= 4, TypeScript >= 3.0 and the experimentalDecorators, emitDecoratorMetadata, types and lib compilation options in your tsconfig.json file.

      {
        "compilerOptions": {
          "baseUrl": ".",
          "outDir": "./dist",
          "target": "es2016",
          "lib": [
            "es2016",
            "dom"
          ],
          "typeRoots": [
            "./node_modules/@types"
          ],
          "module": "commonjs",
          "moduleResolution": "node",
          "experimentalDecorators": true,
          "emitDecoratorMetadata": true,
          "sourceMap": true,
          "declaration": false,
          "allowSyntheticDefaultImports": true
        },
        "include": [
          "./src/**/*.ts"
        ],
        "exclude": [
          "node_modules",
          "./public",
          "dist",
          "test"
        ]
      }
      
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30

      TIP

      You can copy this example of package.json to develop your application:

      {
        "name": "@tsed/basic-example",
        "version": "1.0.0",
        "description": "Here an example to configure your server and how to create your first controller.",
        "main": "src/index.js",
        "scripts": {
          "clean": "rimraf '{src,test}/**/*.{js,js.map}'",
          "build": "yarn tsc",
          "test": "yarn clean && yarn test:lint && yarn test:coverage",
          "test:unit": "cross-env NODE_ENV=test mocha",
          "test:coverage": "cross-env NODE_ENV=test nyc mocha",
          "test:lint": "tslint --project tsconfig.json",
          "test:lint:fix": "tslint --project tsconfig.json --fix",
          "travis:deploy-once": "travis-deploy-once",
          "travis:coveralls": "nyc report --reporter=text-lcov | coveralls",
          "tsc": "tsc --project tsconfig.json",
          "tsc:w": "tsc --project tsconfig.json -w",
          "start": "nodemon --watch \"src/**/*.ts\" --ignore \"node_modules/**/*\" --exec ts-node src/index.ts",
          "start:prod": "cross-env NODE_ENV=production node dist/index.js",
          "docker:build": "yarn build && docker-compose build",
          "deploy": "exit 0"
        },
        "author": "",
        "license": "MIT",
        "dependencies": {
          "@tsed/common": "5.65.3",
          "@tsed/core": "5.65.3",
          "@tsed/di": "5.65.3",
          "@tsed/platform-express": "5.65.3",
          "@tsed/exceptions": "5.65.3",
          "@tsed/swagger": "5.65.3",
          "@types/swagger-schema-official": "2.0.21",
          "body-parser": "1.19.0",
          "cors": "2.8.5",
          "compression": "1.7.4",
          "concurrently": "5.2.0",
          "cookie-parser": "1.4.5",
          "express": "4.17.1",
          "method-override": "^3.0.0",
          "node-uuid": "1.4.8",
          "cross-env": "7.0.2"
        },
        "devDependencies": {
          "@types/chai": "4.2.12",
          "@types/chai-as-promised": "7.1.3",
          "@types/cors": "2.8.6",
          "@types/express": "4.17.7",
          "@types/http-proxy": "1.17.2",
          "@types/mocha": "8.0.1",
          "@types/node": "14.0.27",
          "@types/request-promise": "4.1.45",
          "@types/sinon": "9.0.4",
          "@types/sinon-chai": "3.2.4",
          "@types/supertest": "2.0.10",
          "chai": "4.2.0",
          "chai-as-promised": "7.1.1",
          "concurrently": "5.2.0",
          "mocha": "8.1.1",
          "nodemon": "1.19.4",
          "nyc": "15.1.0",
          "rimraf": "3.0.0",
          "sinon": "9.0.2",
          "sinon-chai": "3.5.0",
          "supertest": "4.0.2",
          "ts-node": "8.10.2",
          "tslint": "6.1.3",
          "typescript": "3.9.4"
        }
      }
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      56
      57
      58
      59
      60
      61
      62
      63
      64
      65
      66
      67
      68

      Then use the command npm install && npm start to start your server.

      # Quick start

      # Create your server

      To use Ts.ED now, use the Platform API to create an application. Platform API gives an abstraction layer between your code written with Ts.ED and the Express code. It means a large part of your code isn't coupled with Express itself, and can be used with another Platform like Koa in the future (Ts.ED v6).

      To facilitate, the v6 migration, the Platform API is already available in v5, but only for Express support with .

        To customize the server settings see Configuration page.

        Finally, create an index.ts file to bootstrap your server, on the same level of the Server.ts:

          You should have this directory tree:

          .
          ├── src
          │   ├── controllers
          │   ├── services
          │   ├── middlewares
          │   ├── index.ts
          │   └── Server.ts
          └── package.json
          
          1
          2
          3
          4
          5
          6
          7
          8

          TIP

          By default Ts.ED loads automatically Services, Controllers and Middlewares in specific directories. This behavior can be changed by editing the componentsScan configuration.

          # Load configuration from file

          It is also possible to use node-config or dotenv to load your configuration from file:

            # Create your first controller

            Create a new CalendarCtrl.ts in your controllers directory (by default root/controllers). All controllers declared with decorators are considered as Express routers. An Express router requires a path (here, the path is /calendars) to expose an url on your server. More precisely, it's a part of a path, and the entire exposed url depends on the Server configuration (see Configuration) and the children controllers.

            In this case, we have no dependencies and the root endpoint is set to /rest. So the controller's url will be http://host/rest/calendars.

            import {Controller, Get} from "@tsed/common";
            
            @Controller("/calendars")
            export class CalendarCtrl {
              @Get()
              findAll(): string {
                return "This action returns all calendars";
              }
            }
            
            1
            2
            3
            4
            5
            6
            7
            8
            9

            TIP

            Decorators , , , , etc..., support dynamic pathParams (eg: /:id) and RegExp like Express API.

            See Controllers section for more details

            WARNING

            You have to configure engine rendering if you want to use the decorator .

            To test your method, just run your server.ts and send an HTTP request on /rest/calendars/1.

            # Ready for More?

            We’ve briefly introduced the most basic features of Ts.ED - the rest of this guide will cover them and other advanced features with much finer details, so make sure to read through it all!