DEV Community: Konstantin Alikhanov

Setting up fullstack TypeScript app

Konstantin Alikhanov — Thu, 28 Feb 2019 21:47:29 +0000

As you know, create-react-app is a grate tool for scaffolding React.JS applications. It support TypeScript. But it only configures frontend part of app. If you need to set up backend too, you may run in to troubles.

In this article I will describe my approach of scaffolding fullstack TypeScript apps.

Basics

First of all lets init our new project folder. I'm gonna use npm.

$ mkdir my-fullstack-typescript-app
$ cd my-fullstack-typescript-app
$ npm init -y

Now we should install typescript package as development dependency.

$ npm i -D typescript

We will have two different tsconfig.json files, one for backend, second for frontend.

Let's generate one from backend.

$ npx tsc --init

This will create tsconfig.json file in our project root directory. I'm gonna to update some fields in it.

Open ./tsconfig.json in your favorite editor and change compilerOptions.target to "es6".

Our source code will be in directory ./src and compiled code in directory ./dist. Uncomment and change options compilerOptions.root and compilerOptions.outDir to "./src" and "./dist" respectively.

Also, I gonna uncomment option compilerOptions.sourceMap to allow debugging of compiled code.

Now your ./tsconfig.json should look like this:

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  }
}

Note: I have removed all other commented fields to keep code short.

Backend

Ok. Let's writing simple backend.

We need to install type definitions for node.js to tell TypeScript information about node.js standrard library.

$ npm i -D @types/node

Also I gonna use express as backend framework and ejs as template engine, so let's install them too.

$ npm i express
$ npm i -D @types/express
$ npm i ejs

Now we can start coding.

Let's create ./src dir and then ./src/config.ts file.

In this file I gonna store some configuration variables for our app.

By now, let's put there just single line of code:

export const SERVER_PORT = parseInt(process.env.SERVER_PORT || "3000");

Ok. Now we can write our web module.

I gonna place whole logic of web module in ./src/web dir.

Create file ./src/web/web.ts with content of our web module:

import express from "express";
import http from "http";
import path from "path";

// Express app initialization
const app = express();

// Template configuration
app.set("view engine", "ejs");
app.set("views", "public");

// Static files configuration
app.use("/assets", express.static(path.join(__dirname, "frontend")));

// Controllers
app.get("/*", (req, res) => {
    res.render("index");
});

// Start function
export const start = (port: number): Promise<void> => {
    const server = http.createServer(app);

    return new Promise<void>((resolve, reject) => {
        server.listen(port, resolve);
    });
};

Two things you can notice here. First — we need view directory ./public. Second — we need static files directory frontend.

Let's create ./public dir (in root of our project) and place there file index.ejs with content:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>My Fullstack TypeScript App</title>

    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
    <meta name="viewport" content="width=device-width, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">

</head>
<body>
    <div id="root"></div>

    <script src="/assets/vendors~main.chunk.js"></script>
    <script src="/assets/main.bundle.js"></script>
</body>
</html>

Here you can see, that we have two script tags, targeting frontend code bundles. We will use Webpack to build frontend budles.

Path to frontend is tricky one. Our frontend code will be stored in ./src/web/frontend dir. But compiled bundle appear in ./dist/web/frontend. We will set up frontend in a minute, but first let's finish backend.

I like to treat with complex module like with a single, so let's create file ./src/web/index.ts with a single line:

export * from "./web";

And we have done with web module.

The last thing left here is to create entry point file ./src/main.ts with following content:

import {SERVER_PORT} from "./config";

import * as web from "./web";

async function main() {
    await web.start(SERVER_PORT);
    console.log(`Server started at http://localhost:${SERVER_PORT}`);
}

main().catch(error => console.error(error));

Our backend is done 🥳. Let's compile it.

Open ./package.json file and add some npm scripts:

"build:backend": "tsc",
"start": "./dist/main.js"

So your ./package.json file should look like this:

{
  "name": "my-fullstack-typescript-app",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build:backend": "tsc",
    "start": "node ./dist/main.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@types/express": "^4.16.1",
    "@types/node": "^11.9.6",
    "typescript": "^3.3.3333"
  },
  "dependencies": {
    "ejs": "^2.6.1",
    "express": "^4.16.4"
  }
}

Now you can chat that this part works:

$ npm run build:backend
$ npm start

But if we visit http://localhost:3000 we will see just black page.

Frontend

By now our project structure looks like:

.
├── dist
│   ├── web
│   │   ├── index.js
│   │   ├── index.js.map
│   │   ├── web.js
│   │   └── web.js.map
│   ├── config.js
│   ├── config.js.map
│   ├── main.js
│   └── main.js.map
├── public
│   └── index.ejs
├── src
│   ├── web
│   │   ├── index.ts
│   │   └── web.ts
│   ├── config.ts
│   └── main.ts
├── package-lock.json
├── package.json
└── tsconfig.json

We are ready to create ./src/web/frontend dir to store our frontend code.

Important thing here: we are using TypeScript compiler with configuration in ./tsconfig.json to compile backend code. But for frontend we will use Webpack and TypeScript configuration in file ./src/web/frontend/tsconfig.json.

So let's create ./src/web/frontend dir and initialize ./src/web/frontend/tsconfig.json file.

$ mkdir ./src/web/frontend
$ cd ./src/web/frontend
$ npx tsc --init

We end up with a tsconfig.json file in ./src/web/frontend/.

Let's open in and make some changes.

Again, set compilerOptions.target to "es6".

Set compilerOptions.module to "esnext".

Uncomment option compilerOptions.sourceMap to allow debugging of frontend bundles.

Uncomment and set compilerOptions.jsx to "react".

Your ./src/web/frontend/tsconfig.json should look like:

{
  "compilerOptions": {
    "target": "es6",
    "module": "esnext",
    "sourceMap": true,
    "jsx": "react",
    "strict": true,
    "esModuleInterop": true
  }
}

Note: we do not specify here compilerOptions.rootDir and compilerOptions.outDir. Files resolution will be done by Webpack.

Now we need to make backend compiler to ignore frontend files.

To do so, we need to add two options to ./tsconfig.json:

"include": ["./src"],
"exclude": ["./src/web/frontend"]

Your ./tsconfig.json should look like:

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["./src"],
  "exclude": ["./src/web/frontend"]
}

Our frontend entry point will be ./src/web/frontend/main.tsx:

import React, {useState} from "react";
import ReactDOM from "react-dom";

import "./style.css";

const App = () => {
    const [counter, setCounter] = useState(0);

    return (
        <div className="App">
            <h1>{counter}</h1>
            <button onClick={() => setCounter(c + 1)}>Press me</button>
        </div>
    )
};

ReactDOM.render(
    <App/>,
    document.getElementById("root"),
);

This is a very simple React.JS app.

Let style it a little bit with ./src/web/frontend/style.css:

.App {
    margin: 30px auto;
    max-width: 320px;
    padding: 2em;
    border: 1px solid silver;
    border-radius: 1em;

    text-align: center;
}

Let's install needed packages:

$ npm i react react-dom
$ npm i -D @types/react @types/react-dom

For building frontend I gonna use Webpack and ts-loader package.

Let's install all of needed stuff:

$ npm i -D webpack webpack-cli ts-loader style-loader css-loader source-map-loader

Now we need to configure Webpack. Let's create ./webpack.config.js with following content:

module.exports = {
    mode: "development",

    entry: {
        main: "./src/web/frontend/main.tsx",
    },

    output: {
        filename: "[name].bundle.js",
        chunkFilename: '[name].chunk.js',
        path: __dirname + "/dist/web/frontend",
        publicPath: "/assets/"
    },

    // Enable sourcemaps for debugging webpack's output.
    devtool: "source-map",

    resolve: {
        // Add '.ts' and '.tsx' as resolvable extensions.
        extensions: [".ts", ".tsx", ".js"]
    },

    module: {
        rules: [
            // All files with a '.ts' or '.tsx' extension will be handled by 'ts-loader'.
            {
                test: /\.tsx?$/,
                loader: "ts-loader",
            },

            // All output '.js' files will have any sourcemaps re-processed by 'source-map-loader'.
            {enforce: "pre", test: /\.js$/, loader: "source-map-loader"},
            {
                test: /\.css$/,
                use: [{loader: "style-loader"}, {loader: "css-loader"}]
            },
        ]
    },

    optimization: {
        splitChunks: {
            chunks: "all"
        },
        usedExports: true
    },
};

And we have done!

Last thing left is to add npm script to ./package.json file to build frontend:

"build:frontend": "webpack"

Now you can test it:

$ npm run build:backend
$ npm run build:frontend
$ npm start

Goto http://localhost:3000

Full code can be found here.

Have a nice day!

How can I reduce amount of boilerplate code while working with TypeScript+mongoose 🙈

Konstantin Alikhanov — Thu, 28 Feb 2019 11:07:03 +0000

Let's say I have two entities: Vehicle and Tariff. They are related as 1-to-many (vehicle can has many tariffs).

This is my basic types definition of objects, I want to work with:

interface Tariff {
    id: string;         // <-- ID of entity
    createdAt: Date;    // <-- some meta data fields for sorting and etc.

    days: number;       // <-- userful info
    price: number;      // <-
}

interface Vehicle {
    id: string;          // <-- ID of entity
    createdAt: Date;     // <-- some meta data fields for sorting and etc.

    model: string;       // <-- userful info
    year?: string;       // <-
    seatsCount?: number; // <-
    tariffs: Tariff[];   // <-- array of tariffs
}

Looks great. No we need to create database model. First let's define mongoose schema:

import mongoose from "mongoose";

const vehicleSchema = new mongoose.Schema({
    createdAt: {type: Date, required: true, default: () => new Date()},

    model: {type: String, required: true},
    year: String,
    seatsCount: Number,
});

Awesome. I decided no to put tariffs inside vehicle documents and they will be stored separately.

Next we need to create mongoose model. But we need to provide generic type extending mongoose.Document to mongoose.model. And this is where code duplication begins:

// First we need to define TypeScript schema equalent of mongoose schema:
interface VehicleSchema {
    createdAt: Date;

    model: string;
    year?: string;
    seatsCount?: number;
}

// Then we need to defined a new type of out vehicle models:
type VehicleModel = VehicleSchema && mongoose.Document;

// And finaly we can create model:
const VehicleModel = mongoose.model<VehicleModel>("Car", carSchema);

// Look, here is a type named "VehicleModel" and a constant named "VehicleModel"

Now we can write functions for CRUD operations:

namespace vehicle {
    export const create = async (form: VehicleCreateForm): Promise<Vehicle> => {
        const fields = toDb(form);

        // assume form is prevalidated
        let dbVehicle = new VehicleModel(form);
        dbVehicle = await model.save();

        // tariff - is the separate module, like this one,  
        // createAllFor methods retuns Tariff[]
        const tariffs = await tariff.createAllFor(dbVehicle.id, form.tariffs);

        return fromDb(dbVehicle, tariffs);
    }

    //...

    // export const update = ...
    // export const list = ...
    // export const get = ...    
    // etc..
}

Here we intoduce one extra type: VehicleCreateForm, it describes all fields needed to create vehicle:

interface VehicleCreateForm {
    model: string;
    year?: string;
    seatsCount?: number;
    tariffs: TariffCreateFields[]; // <-- here is another one special type
}

interface TariffCreateFields {
    days: number;
    price: number;
}

Also we need to define two functions: toDb to prevent some fields, f.e. tariffs be passed to model. And fromDb "translates" model to Vehicle entity, removes or converts some fields:

const u = <T>(value: T | undefined | null): (T | undefined) => value === null ? undefined : value;

const toDb = (f: VehicleCreateForm): VehicleCreateFields => ({
    model: f.model,
    year: f.year,
    seatsCount: f.seatsCount,
});

const fromDb = (m: VehicleModel, tariffs: Tariff[]): Vehicle => ({
    id: m.id,
    createdAt: m.createdAt,

    model: m.model,
    year: u(m.year),
    tariffs,
});

And, yaaa, we need one more extra type: VehicleCreateFields. Fields we are passing to model constructor.

interface VehicleCreateFields {
    model: string;
    year?: string;
    seatsCount?: number;
}

Seems like here is done.

Also we need to define tariff namespace similar to vehicle. All types and will be duplicated too: TariffSchema, TariffModel, TariffCreateForm, TariffCreateDocument.

And this will happen for every new entity. In current case I can avoid creating VehicleUpdateFields type and use VehicleCreateFields for creating and updating. There could be also VehicleUpdateDocument and etc.

How can I reduce the amount of code duplications. How you deal with typescript/mongoose?

Ofcouse I can extract common fields to "common chunck" interfaces, but I event don't know how to name them. I tried to use interface inherence, end up with messy hell of small types. Like:

interface Entity {
    id: string;
    createdAt: Date;
}

interface VehicleOwnFields {
    model: string;
    year?: string;
    seatsCount?: number;
}

interface VehicleOwnFields {
    model: string;
    year?: string;
    seatsCount?: number;
}

interface VehicleExternalFields {
    tariffs: Tariff[];
}

type Vehicle = Entity && VehicleOwnFields && VehicleExternalFields;
// and so on...

I think this is not the best solution.

Also there can be cases when fields has different types in Entity and in Schema. F.e. I can decide to serialize Tariff[] to JSON and store as string field in VehicleModel.

I think this is general problem for typescript and ORMs.
If you know good articles where this problem is described, please give me link.