
This article will guide you through setting up a basic web application using Yarn's workspace, TypeScript, esbuild, Express, and React. At the end of this tutorial you will have a fully buildable and deployable web application.

1. [Setting up the project — part 1](/post/app-yarn-typescript-esbuild-part-1)
2. [Adding code — part 2](/post/app-yarn-typescript-esbuild-part-2)
3. [Building the app — part 3](/post/app-yarn-typescript-esbuild-part-3)
4. **[Going further — advanced](/post/app-yarn-typescript-esbuild-part-going-further)**
   1. [Docker](#docker)
   2. [Building and publishing our Docker image with GitHub Actions](#actions)
   3. [Deploying our Docker image to Heroku automatically](#heroku)
   4. [Summary](#summary)

Want to see the full code? Check out the repository on GitHub at [halftheopposite/tutorial-app](https://github.com/halftheopposite/tutorial-app).

---

This post comes as an appendix to the previous 3-part tutorial on building a modern web application. The focus of this appendix is to help you deploy your application using **containers** (Docker), **continuous integration** (GitHub Actions), and **continuous deployment** (Heroku). The information below can be applied to any existing application, but for simplicity I will use the app that we have built so far.

## <a name="docker"></a>Docker 🐳

This section will assume that you are already familiar with the concept of containers.

<p class="hint-info">
To be able to create an image out of our code, we will need to have Docker installed on our machine. To see how to install it based on the OS, please take a moment to look at the <a href="https://docs.docker.com/get-started/#download-and-install-docker">official documentation</a>.
</p>

### Dockerfile

To generate a Docker image, the first step is to create a `Dockerfile` at the root of our project (these steps could be done entirely through the CLI, but using a configuration file is the default way of defining build steps).

```dockerfile
FROM node:14.15.5-alpine

WORKDIR /usr/src/app

# Install dependencies early so that if some files in our app
# change, Docker won't have to download the dependencies again,
# and instead will start from the next step ("COPY . .").
COPY ./package.json .
COPY ./yarn.lock .
COPY ./packages/app/package.json ./packages/app/
COPY ./packages/common/package.json ./packages/common/
COPY ./packages/server/package.json ./packages/server/
RUN yarn

# Copy all files of our app (except files specified in the .gitignore)
COPY . .

# Build app
RUN yarn build

# Port
EXPOSE 3000

# Serve
CMD [ "yarn", "serve" ]
```

I'll try to detail as much as possible what is going on here and why the order of these steps is important:

1. `FROM` tells Docker to use the specified base image for the current context. In our case, we want to have an environment ready to run Node.js applications.
2. `WORKDIR` sets the current working directory in the container.
3. `COPY` copies a file or folder from the current local directory (project's root), to the working directory in the container. As you can see, we only copy files related to **dependencies** in this step. This is because Docker caches each result of a command on each build as a _layer_. Since we want to optimize build time and bandwidth, we only want to reinstall dependencies if they have changed (which happens less often than files changes in general).
4. `RUN` executes a command in the shell.
5. `EXPOSE` is the internal port used for the container (has nothing to do with the `PORT` env for our app). Any value should be good here, but if you want to know more you can have a look at the [official documentation](https://docs.docker.com/engine/reference/builder/#expose).
6. `CMD` purpose is to provide defaults for executing a container.

If you'd like to learn more about these keywords you can check the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/).

### Adding a .dockerignore

Using a `.dockerignore` file is not mandatory but highly recommended to:

- Ensure you're not copying junk files to your container.
- Make the use of the `COPY` command easier.

It works exactly like a `.gitignore` file if you're already familiar with it. You can copy the content below into a `.dockerignore` file at the same level of your `Dockerfile` and it will be picked up automatically.

```shell
README.md

# Git
.gitignore

# Logs
yarn-debug.log
yarn-error.log

# Binaries
node_modules
*/*/node_modules

# Builds
*/*/build
*/*/dist
*/*/script.js
```

Feel free to add any files you'd like to ignore to lighten up your final image.

### Building

Now that our app is ready for Docker, we need a way to generate an actual image out of it. To do so, we will add a new command to our root `package.json`:

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "license": "MIT",
  "private": true,
  "workspaces": ["packages/*"],
  "devDependencies": {
    "esbuild": "^0.9.6",
    "ts-node": "^9.1.1",
    "typescript": "^4.2.3"
  },
  "scripts": {
    "app": "yarn workspace @my-app/app",
    "common": "yarn workspace @my-app/common",
    "server": "yarn workspace @my-app/server",
    "build": "ts-node ./scripts/build.ts",
    "serve": "node ./packages/server/dist/index.js",
    "docker": "docker build . -t my-app" // Add this line
  }
}
```

The `docker build . -t my-app` commands tells docker to use the current (`.`) directory to look for a `Dockerfile` and to name the resulting image (`-t`) as `my-app`.

<p class="hint-info">
Make sure that you have the Docker daemon running in order to use the <code>docker</code> command in your terminal.
</p>

Now that the command is in our project's scripts, you can run it with `yarn docker`.

You should expect the following terminal output once you run the command:

```shell
Sending build context to Docker daemon  76.16MB
Step 1/12 : FROM node:14.15.5-alpine
 ---> c1babb15a629
Step 2/12 : WORKDIR /usr/src/app
 ---> b593905aaca7
Step 3/12 : COPY ./package.json .
 ---> e0046408059c
Step 4/12 : COPY ./yarn.lock .
 ---> a91db028a6f9
Step 5/12 : COPY ./packages/app/package.json ./packages/app/
 ---> 6430ae95a2f8
Step 6/12 : COPY ./packages/common/package.json ./packages/common/
 ---> 75edad061864
Step 7/12 : COPY ./packages/server/package.json ./packages/server/
 ---> e8afa17a7645
Step 8/12 : RUN yarn
 ---> 2ca50e44a11a
Step 9/12 : COPY . .
 ---> 0642049120cf
Step 10/12 : RUN yarn build
 ---> Running in 15b224066078
yarn run v1.22.5
$ ts-node ./scripts/build.ts
Done in 3.51s.
Removing intermediate container 15b224066078
 ---> 9dce2d505c62
Step 11/12 : EXPOSE 3000
 ---> Running in f363ce55486b
Removing intermediate container f363ce55486b
 ---> 961cd1512fcf
Step 12/12 : CMD [ "yarn", "serve" ]
 ---> Running in 7debd7a72538
Removing intermediate container 7debd7a72538
 ---> df3884d6b3d6
Successfully built df3884d6b3d6
Successfully tagged my-app:latest
```

And that's it! Our image is now created and registred on our machine for Docker to use. If you wish to list the available Docker images, you can run the `docker image ls` command:

```shell
→ docker image ls
REPOSITORY    TAG       IMAGE ID        CREATED          SIZE
my-app        latest    df3884d6b3d6    4 minutes ago    360MB
```

### Running with the command like

To run an available Docker image through the command line is pretty straightforward: `docker run -d -p 3000:3000 my-app`.

- `-d` runs the container in detached mode (in the background).
- `-p` sets the port on which to expose the container (format is `[host port]:[container port]`). So if we wanted to expose port `3000` inside the container (remember our `EXPOSE` argument in the Dockerfile) to port `8000` outside the container, we would pass `8000:3000` to the `-p` flag.

You can confirm that your container is running with `docker ps`. This will list all running containers:

<p class="hint-info">
If you have other requirements and questions regarding the launch of containers you will find more information <a href="https://docs.docker.com/language/nodejs/run-containers">here</a>
</p>

```shell
→ docker ps
CONTAINER ID    IMAGE     COMMAND                  CREATED          STATUS          PORTS                    NAMES
71465a89b58b    my-app    "docker-entrypoint.s…"   7 seconds ago    Up 6 seconds    0.0.0.0:3000->3000/tcp   determined_shockley
```

Now, open your browser and navigate to the following URL http://localhost:3000/ to see you application running 🚀!

## <a name="actions"></a>Building and publishing a Docker image with GitHub Actions

<p class="hint-info">
This step is not required if you only want to deploy your application on Heroku.
</p>

Now that we know how to build and run a Docker image locally, we want to learn how to do this automatically. This process is called **Continuous Integration** and usually relies on external services to start a serie of automatic build steps for example (linting, testing, building).

In this tutorial we will use GitHub's Actions to trigger an automatic Docker build and image publishing to GitHub packages whenever your commit some changes on the `master` (or `main`) branch.

At the root of the project, create the following nested folders `.github/workflows/`. Once these folder added, create a `docker-publish.yml` file into `workflows/` and copy the content of the snippet below into it:

```yml
name: Publish Docker image

on:
  push:
    branches:
      - master
      - main

jobs:
  push_to_registry:
    name: Push Docker image to GitHub Packages
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Publish to GitHub Packages
        uses: docker/build-push-action@v1
        with:
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
          registry: docker.pkg.github.com
          repository: USERNAME/REPOSITORY/NAME
          tag_with_ref: true
```

This action is split in two steps:

1. Checkout the `master` (or `main`) branch of the repository.
2. Build a Docker image and publish it to the repository's packages (GitHub Packages).

Before doing anything more you'll need to make some changes to the `repository` property:

- Replace `USERNAME` with your own GitHub username
- Replace `REPOSITORY` with the title of your repository
- Replace `NAME` with a name for your package

You can now **commit** this file and make some changes to your code (or run a CI worlflow manually) to see the magic happen.

Packages will be published in your **profile page** on GitHub. If you click on a published package, you will be able to see the fully qualified name to pull and run your Docker image (ex: `docker.pkg.github.com/USERNAME/REPOSITORY/NAME:latest`).

## <a name="heroku"></a>Deploying our Docker image to Heroku automatically

GitHub Actions are now ready, and the last thing we need is to finally run our application. Many hosting providers exist, but few offer automatic deploys with a Docker image AND a free tier. That's why we'll go with Heroku which provide both.

### Creating an application in Heroku

I won't dive into too many details about Heroku, instead I will provide a step-by-step guide to setup the environment in accordance to our GitHub Action, but feel free to look for more on your side.

1. Log in Heroku (or create a new account if you don't have any yet)
2. Go to your app dashboard (or click https://dashboard.heroku.com/apps)
3. Click on `New > Create new app` (or click https://dashboard.heroku.com/new-app)
4. Type an available name, select the region you prefer, and press `Create app`
5. Now, navigate to your account settings (or click https://dashboard.heroku.com/account)
6. Scroll down to the **API Key** section and create a new key if none exist

And that's it! You should keep this page open as we'll need to use the API key in our workflow.

### Implementing the GitHub Action

Our Heroku application instance is now ready and we can start implementing our action in GitHub. Navigate to the `.github/workflows/` folder (or create it if you've skipped the previous step), and add a `heroku-deploy.yml` file into it.

```yml
name: Deploy to Heroku

on:
  push:
    branches:
      - master
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

        # This action will automatically build our docker image using
        # the Dockerfile in the project's root, and publish it to our
        # Heroku application instance.
      - name: Deploy to Heroku
        id: heroku
        uses: jctaveras/heroku-deploy@v2.1.3
        with:
          email: ${{ secrets.HEROKU_EMAIL }}
          api_key: ${{ secrets.HEROKU_API_KEY }}
          app_name: ${{ secrets.HEROKU_APP_NAME }}
          dockerfile_path: '.'
```

The variables appearing as `${{ secrets.[...] }}` are called GitHub **secrets**. They are special marks that the GitHub runner will replace at build time with values in your project's settings. This avoids publishing sensitive information directly into your code and to make it easier to share open-source projects.

To create the secrets we need, follow a few simple steps (also available [here](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository)):

1. On GitHub, navigate to the main page of the repository.
2. Under your repository name, click `Settings`.
3. In the left sidebar, click `Secrets`.
4. Click `New repository secret`.
5. Type a name for your secret in the `Name` (ex: `HEROKU_EMAIL`) input box.
6. Enter the value for your secret.
7. Click `Add secret`.

You must do this for each of our 3 properties:

- `HEROKU_EMAIL` is the email you use to log into your Heroku account
- `HEROKU_API_KEY` is the API key we created
- `HEROKU_APP_NAME` is the the of your application in Heroku

Once everything is filled up, you will need to push a new commit on your `master` (or `main`) branches, or trigger a new CI workflow. If everything went according to plan your application should now be available on a similar URL [http://YOUR_APP_ID.herokuapp.com/]() (make sure to replace `YOUR_APP_ID` with your application's name).

## <a name="summary"></a>Summary

If you've read up to here, than kudos to you! You've learned how to containerize an application, host a Docker image, and deploy an application automatically to Heroku. This should get you started on the right path the develop any modern web app that comes to your mind.

If you still have some questions regarding the project architecture and code, feel free to reach out to me and to checkout the [halftheopposite/tutorial-app](https://github.com/halftheopposite/tutorial-app) GitHub repository coming with this article.


The last part of a step-by-step guide on setting up a fully functional web application using Yarn's workspace, TypeScript, esbuild, React and Express.

Creating a web application using Yarn workspace, TypeScript, esbuild, React, and Express — advanced


This article will guide you through setting up a basic web application using Yarn's workspace, TypeScript, esbuild, Express, and React. At the end of this tutorial you will have a fully buildable and deployable web application.

1. [Setting up the project — part 1](/post/app-yarn-typescript-esbuild-part-1)
2. [Adding code — part 2](/post/app-yarn-typescript-esbuild-part-2)
3. **[Building the app — part 3](/post/app-yarn-typescript-esbuild-part-3)**
   1. [Bundlers](#bundlers)
   2. [Build](#build)
   3. [Serve](#serve)
   4. [Summary](#summary)
   5. [What's next?](#what-is-next)
4. [Going further — advanced](/post/app-yarn-typescript-esbuild-part-going-further)

Want to see the full code? Check out the repository on GitHub at [halftheopposite/tutorial-app](https://github.com/halftheopposite/tutorial-app).

---

In this third and final part, we will implement the scripts used to build and launch our application.

## <a name="bundlers"></a>Bundlers

To transpile our TypeScript code into interpretable JavaScript, and to bundle all external libraries into a single file, we will be using a bundler tool. Many bundlers are available in the JS/TS ecosystem, such as [WebPack](https://webpack.js.org/), [Parcel](https://parceljs.org/), or [Rollup](https://github.com/rollup/rollup), but the one that we will be choosing is [esbuild](https://esbuild.github.io/). In comparison to others bundlers, `esbuild` comes with many features loaded by default (TypeScript, React) and has **huge** performances gains (up to a hundred times faster). If you're interested in knowing more, please take a time to read this [FAQ](https://esbuild.github.io/faq/#benchmark-details) by the author.

The scripts will require the following dependencies:

- [esbuild](https://www.npmjs.com/package/esbuild) is our bundler
- [ts-node](https://www.npmjs.com/package/ts-node) is a REPL for TypeScript that we will use to execute our scripts

From the project's root, run: `yarn add -D -W esbuild ts-node`.

`package.json`

```json
{
  "name": "my-app",
  "version": "1.0",
  "license": "UNLICENSED",
  "private": true,
  "workspaces": ["packages/*"],
  "devDependencies": {
    "esbuild": "^0.9.6",
    "ts-node": "^9.1.1",
    "typescript": "^4.2.3"
  },
  "scripts": {
    "app": "yarn workspace @my-app/app",
    "common": "yarn workspace @my-app/common",
    "server": "yarn workspace @my-app/server"
  }
}
```

## <a name="build"></a>Build

We now have all the tools needed to build our application, so let's create our first script.

Start by creating a new folder named `scripts/` at the project's root.

<p class="hint-info">
Our script will be written in TypeScript and executed with <code>ts-node</code> from the command line. Although a CLI exists for <code>esbuild</code>, it is more convenient to use the library through JS or TS if you want to pass more complex parameters or to combine multiple workflows together.
</p>

Create a `build.ts` file inside the `scripts/` folder and add the code below (I will explain what the code does through comments):

`scripts/build.ts`

```ts
import { build } from 'esbuild';

/**
 * Generic options passed during build.
 */
interface BuildOptions {
  env: 'production' | 'development';
}

/**
 * A builder function for the app package.
 */
export async function buildApp(options: BuildOptions) {
  const { env } = options;

  await build({
    entryPoints: ['packages/app/src/index.tsx'], // We read the React application from this entrypoint
    outfile: 'packages/app/public/script.js', // We output a single file in the public/ folder (remember that the "script.js" is used inside our HTML page)
    define: {
      'process.env.NODE_ENV': `"${env}"`, // We need to define the Node.js environment in which the app is built
    },
    bundle: true,
    minify: env === 'production',
    sourcemap: env === 'development',
  });
}

/**
 * A builder function for the server package.
 */
export async function buildServer(options: BuildOptions) {
  const { env } = options;

  await build({
    entryPoints: ['packages/server/src/index.ts'],
    outfile: 'packages/server/dist/index.js',
    define: {
      'process.env.NODE_ENV': `"${env}"`,
    },
    external: ['express'], // Some libraries have to be marked as external
    platform: 'node', // When building for node we need to setup the environement for it
    target: 'node14.15.5',
    bundle: true,
    minify: env === 'production',
    sourcemap: env === 'development',
  });
}

/**
 * A builder function for all packages.
 */
async function buildAll() {
  await Promise.all([
    buildApp({
      env: 'production',
    }),
    buildServer({
      env: 'production',
    }),
  ]);
}

// This method is executed when we run the script from the terminal with ts-node
buildAll();
```

The code is pretty self-explanatory, but if you feel that you're missing pieces you can have a look at `esbuild`'s [API documentation](https://esbuild.github.io/api/#build-api) to have a complete list of keywords.

Our build script is now complete! The last thing we need to do is to add a new command into our `package.json` to conveniently run the build operations.

```json
{
  "name": "my-app",
  "version": "1.0",
  "license": "UNLICENSED",
  "private": true,
  "workspaces": ["packages/*"],
  "devDependencies": {
    "esbuild": "^0.9.6",
    "ts-node": "^9.1.1",
    "typescript": "^4.2.3"
  },
  "scripts": {
    "app": "yarn workspace @my-app/app",
    "common": "yarn workspace @my-app/common",
    "server": "yarn workspace @my-app/server",
    "build": "ts-node ./scripts/build.ts" // Add this line here
  }
}
```

We can now run `yarn build` from the project's root folder to launch the build process everytime you make changes to your project (we will see how we can add hot-reloading in another post).

**Structure reminder:**

```
my-app/
├─ packages/
├─ scripts/
│  ├─ build.ts
├─ package.json
├─ tsconfig.json
```

## <a name="serve"></a>Serve

Our application is built and ready to be served to the world, and we just need to add a last command to our `package.json`:

```json
{
  "name": "my-app",
  "version": "1.0",
  "license": "UNLICENSED",
  "private": true,
  "workspaces": ["packages/*"],
  "devDependencies": {
    "esbuild": "^0.9.6",
    "ts-node": "^9.1.1",
    "typescript": "^4.2.3"
  },
  "scripts": {
    "app": "yarn workspace @my-app/app",
    "common": "yarn workspace @my-app/common",
    "server": "yarn workspace @my-app/server",
    "build": "ts-node ./scripts/build.ts",
    "serve": "node ./packages/server/dist/index.js" // Add this line here
  }
}
```

Since we are now dealing with pure JavaScript we can use the `node` binary to launch our server. So go on and run `yarn serve`.

If you look at the console you'll see that the server is successfully listening. You can also open a web browser and navigate to http://localhost:3000 to display your functional React application 🎉!

<p class="hint-info">
If you'd like to change the port at runtime, you can launch the <code>serve</code> command by prefixing it with an environment variable: <code>PORT=4000 yarn serve</code>.
</p>

## <a name="summary"></a>Summary

If you've read this far, then congratulations on completing your modern web application! If you still have questions or feedback on this serie of articles, please do not hesitate to reach out.

## <a name="what-is-next"></a>What's next?

Some things that we will explore in an appendix post:

- Creating a containerized application with **Docker**
- Adding CI with **GitHub Actions**
- Deploying our container to **Heroku**
- Adding a hot-reloading mode with `esbuild`


The third and final part will finish setting up all the necessary build script with esbuild and to serve your React application.

Creating a web application using Yarn workspace, TypeScript, esbuild, React, and Express — part 3

This article will guide you through setting up a basic web application using Yarn's workspace, TypeScript, esbuild, Express, and React. At the end of this tutorial you will have a fully buildable and deployable web application.

1. [Setting up the project — part 1](/post/app-yarn-typescript-esbuild-part-1)
2. **[Adding code — part 2](/post/app-yarn-typescript-esbuild-part-2)**
   1. [Common](#common)
   2. [App](#app)
   3. [Server](#server)
   4. [Summary](#summary)
3. [Building the app — part 3](/post/app-yarn-typescript-esbuild-part-3)
4. [Going further — advanced](/post/app-yarn-typescript-esbuild-part-going-further)

Want to see the full code? Check out the repository on GitHub at [halftheopposite/tutorial-app](https://github.com/halftheopposite/tutorial-app).

---

The second part will focus on adding the code to our `common`, `app`, and `server` packages.

## <a name="common"></a>Common

We will start with `common` as this package will be used by both `app` and `server`. It's goal is to provide shared logic and variables.

### Files

For the purpose of this tutorial the `common` package will be quite simple. First, start by adding a new folder:

- A `src/` folder, containing our package's code.

Once this folder has been created, add the following file into it:

`src/index.ts`

```ts
export const APP_TITLE = 'my-app';
```

Now that we have some code to export, we want to tell TypeScript where to look for it when importing it from other packages. To do so, we will need to update the `package.json` file:

`package.json`

```json
{
  "name": "@my-app/common",
  "version": "0.1.0",
  "license": "UNLICENSED",
  "private": true,
  "main": "./src/index.ts" // Add this line to provide TS with an entrypoint to this package.
}
```

We have now completed the `common` package!

**Structure reminder:**

```
common/
├─ src/
│  ├─ index.ts
├─ package.json
```

## <a name="app"></a>App

### Dependencies

The `app` package will need the following dependencies:

- [react](https://www.npmjs.com/package/react)
- [react-dom](https://www.npmjs.com/package/react-dom)

From the project's root, run:

- `yarn app add react react-dom`
- `yarn app add -D @types/react @types/react-dom` (to add the typings for TypeScript)

`package.json`

```json
{
  "name": "@my-app/app",
  "version": "0.1.0",
  "license": "UNLICENSED",
  "private": true,
  "dependencies": {
    "@my-app/common": "^0.1.0", // Notice that we've added this import manually
    "react": "^17.0.1",
    "react-dom": "^17.0.1"
  },
  "devDependencies": {
    "@types/react": "^17.0.3",
    "@types/react-dom": "^17.0.2"
  }
}
```

### Files

To create our React application we will need to add two new folders:

- A `public/` folder, that will hold the base HTML page and our assets.
- A `src/` folder, containing our application's code.

Once these two folders have been created, we can start by adding the HTML file that will be our application's host.

`public/index.html`

```html
<!DOCTYPE html>
<html>
  <head>
    <title>my-app</title>
    <meta name="description" content="Welcome on my application!" />
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    
    <div id="root"></div>
    
    <script src="script.js"></script>
  </body>
</html>
```

Now that we have a page to render, we can implement our very basic, but functional, React application, by adding the two files below.

`src/index.tsx`

```tsx
import * as React from 'react';
import * as ReactDOM from 'react-dom';

import { App } from './App';

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

This code hooks into the `root` div from our HTML file and injects the React component tree into it.

`src/App.tsx`

```tsx
import { APP_TITLE } from '@my-app/common';
import * as React from 'react';

export function App(): React.ReactElement {
  const [count, setCount] = React.useState(0);

  return (
    <div>
      <h1>Welcome on {APP_TITLE}!</h1>
      <p>
        This is the main page of our application where you can confirm that it
        is dynamic by clicking the button below.
      </p>

      <p>Current count: {count}</p>
      <button onClick={() => setCount((prev) => prev + 1)}>Increment</button>
    </div>
  );
}
```

This simple `App` component will render our app's title and a dynamic counter. It will be the entrypoint to our React tree. Feel free to add any code that you would like.

And that's it! We've completed our very basic React application. It doesn't do much for now, but we can always come back to it later and add more features.

**Structure reminder:**

```
app/
├─ public/
│  ├─ index.html
├─ src/
│  ├─ App.tsx
│  ├─ index.tsx
├─ package.json
```

## <a name="server"></a>Server

### Dependencies

The `server` package will need the following dependencies:

- [cors](https://www.npmjs.com/package/cors)
- [express](https://www.npmjs.com/package/express)

From the project's root, run:

- `yarn server add cors express`
- `yarn server add -D @types/cors @types/express` (to add the typings for TypeScript)

`package.json`

```json
{
  "name": "@my-app/server",
  "version": "0.1.0",
  "license": "UNLICENSED",
  "private": true,
  "dependencies": {
    "@my-app/common": "^0.1.0", // Notice that we've added this import manually
    "cors": "^2.8.5",
    "express": "^4.17.1"
  },
  "devDependencies": {
    "@types/cors": "^2.8.10",
    "@types/express": "^4.17.11"
  }
}
```

### Files

Our React app is now ready, and the last part that we need is a server to serve it. Start by creating the following folder to it:

- A `src/` folder, containing our server's code.

Next, add the main file for our server:

`src/index.ts`

```typescript
import { APP_TITLE } from '@my-app/common';
import cors from 'cors';
import express from 'express';
import { join } from 'path';

const PORT = 3000;

const app = express();
app.use(cors());

// Serve static resources from the "public" folder (ex: when there are images to display)
app.use(express.static(join(__dirname, '../../app/public')));

// Serve the HTML page
app.get('*', (req: any, res: any) => {
  res.sendFile(join(__dirname, '../../app/public', 'index.html'));
});

app.listen(PORT, () => {
  console.log(`${APP_TITLE}'s server listening at http://localhost:${PORT}`);
});
```

This is a very basic Express application, but if we don't have anything else beside a Single-Page Application to serve, then that's pretty much all we need.

**Structure reminder:**

```
server/
├─ src/
│  ├─ index.ts
├─ package.json
```

## <a name="summary"></a>Summary

All modules are now ready and our small app has all the code it needs to run. However, since we are using TypeScript, which is not pure JavaScript, we need to a way to convert all our files into something that is parsable and executable by Node.js (for our server), or the browser (for our React application). This step is called _transpiling_. The next post will explain how to build and serve our application using a bundler.

The second part will focus on creating the code for our React application and setting up the Express server.

Creating a web application using Yarn workspace, TypeScript, esbuild, React, and Express — part 2


This article will guide you through setting up a basic web application using Yarn's workspace, TypeScript, esbuild, Express, and React. At the end of this tutorial you will have a fully buildable and deployable web application.

1. **[Setting up the project — part 1](/post/app-yarn-typescript-esbuild-part-1)**
   1. [Workspaces](#workspaces)
   2. [TypeScript](#typescript)
   3. [Adding the first scripts](#adding-the-first-scripts)
   4. [Preparing fot Git](#preparing-for-git)
2. [Adding code — part 2](/post/app-yarn-typescript-esbuild-part-2)
3. [Building the app — part 3](/post/app-yarn-typescript-esbuild-part-3)
4. [Going further — advanced](/post/app-yarn-typescript-esbuild-part-going-further)

Want to see the full code? Check out the repository on GitHub at [halftheopposite/tutorial-app](https://github.com/halftheopposite/tutorial-app).

---

This project will be structured as a monorepo. The goal of a monorepo is to improve the amount of code shared between modules and to better anticipate how those modules communicate together (in a micro-service architecture for example). For the purpose of this exercise we will keep the structure simple:

- An `app`, which will represent our React website.
- A `server`, which will serve our app using Express.
- And `common`, where some code will be shared among `app` and `server`.

<p class="hint-info">
The only requirement before setting up the project is to have <code>yarn</code> installed on your machine. Yarn is a package manager in the same way as <code>npm</code>, but with better performances and slightly more features. You can read more on how to install it on the <a href="https://classic.yarnpkg.com/en/docs/install/">official documentation</a>.
</p>

## <a name="workspaces"></a>Workspaces

Navigate to the folder where you want to initialize the project, and follow these steps through your favourite terminal:

1. Create the project's folder with `mkdir my-app` (feel free to choose the name you want).
2. Navigate to it with `cd my-app`.
3. Initialize it with `yarn init`. This will prompt you with questions to create the initial `package.json` file (do not worry, you can modify this at any time once the file has been created). If you don't want to use the `yarn init` command you can always create the file manually and copy the content below into it:

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "license": "UNLICENSED",
  "private": true // Required for yarn workspace to work
}
```

Now that the `package.json` file has been created, we need to create the folders for our modules `app`, `common`, and `server`. To facilitate the discovery of modules by `yarn workspace` and improve project's readability, we will nest our modules under a `packages` folder:

```typescript
my-app/
├─ packages/ // Where all our current and future modules will live
│  ├─ app/
│  ├─ common/
│  ├─ server/
├─ package.json
```

Each of our module will act as a small and independent project and will require its own `package.json` to manage dependencies. To setup each one of them we can either use `yarn init` (in each folder) or create the files manually (through the IDE for example).

<p class="hint-info">
The naming convention used for the packages' names is to prefix each one of them with <code>@my-app/*</code>. This is called a scope in the NPM land (you can read more <a href="https://docs.npmjs.com/about-scopes">here</a>). You do not have to prefix yours like so, but it greatly helps later on.
</p>

Once you have created and initialized all three packages you should have something quite similar as below.

The `app` package:

```json
{
  "name": "@my-app/app",
  "version": "0.1.0",
  "license": "UNLICENSED",
  "private": true
}
```

The `common` package:

```json
{
  "name": "@my-app/common",
  "version": "0.1.0",
  "license": "UNLICENSED",
  "private": true
}
```

The `server` package:

```json
{
  "name": "@my-app/server",
  "version": "0.1.0",
  "license": "UNLICENSED",
  "private": true
}
```

Finally, we need to tell `yarn` where to look for the modules, so go back and edit the project's `package.json` file and add the following `workspaces` property (If you want to know more about the details, go look at [Yarn's](https://classic.yarnpkg.com/en/docs/workspaces/) documentation for workspaces).

```json
{
  "name": "my-app",
  "version": "1.0",
  "license": "UNLICENSED",
  "private": true,
  "workspaces": ["packages/*"] // Add this here
}
```

Your final folder structure should look like so:

```
my-app/
├─ packages/
│  ├─ app/
│  │  ├─ package.json
│  ├─ common/
│  │  ├─ package.json
│  ├─ server/
│  │  ├─ package.json
├─ package.json
```

You're now done setting up the basics for our project.

## <a name="typescript"></a>TypeScript

We will now add our first dependency to our project: TypeScript. TypeScript is a superset of JavaScript that implements types checking at build time.

Go to the project's root folder through your terminal and run `yarn add -D -W typescript`.

- Argument `-D` adds TypeScript to the `devDependencies` since we only it during development and build time.
- Argument `-W` allows a package to be installed at the workspaces root, making it available globally to `app`, `common`, and `server`.

Your `package.json` should look like:

```json
{
  "name": "my-app",
  "version": "1.0",
  "license": "UNLICENSED",
  "private": true,
  "workspaces": ["packages/*"],
  "devDependencies": {
    "typescript": "^4.2.3"
  }
}
```

This will also create a `yarn.lock` file (which ensures throughout the life of the project that the intended versions of a dependency stay the same), and a `node_modules` folder which hold the binaries of our dependencies.

Now that we have TypeScript installed, a good practice is to tell it how to behave. To do so, we will add a configuration file that should be picked up by your IDE (automatically if you use VSCode).

At the root of the project create a `tsconfig.json` file and copy the content below into it:

```json
{
  "compilerOptions": {
    /* Basic */
    "target": "es2017",
    "module": "CommonJS",
    "lib": ["ESNext", "DOM"],

    /* Modules Resolution */
    "moduleResolution": "node",
    "esModuleInterop": true,

    /* Paths Resolution */
    "baseUrl": "./",
    "paths": {
      "@my-app/*": ["packages/*"]
    },

    /* Advanced */
    "jsx": "react",
    "experimentalDecorators": true,
    "resolveJsonModule": true
  },
  "exclude": ["node_modules", "**/node_modules/*", "dist"]
}
```

You can easily search for each of the `compilerOptions` properties and their actions, but the one that is the most useful to us is the `paths` property. This one tells TypeScript where to look for code and typings when using the `@my-app/common` import in the `@my-app/server` or `@my-app/app` packages for example.

Your current project structure should now look like this:

```
my-app/
├─ node_modules/
├─ packages/
│  ├─ app/
│  │  ├─ package.json
│  ├─ common/
│  │  ├─ package.json
│  ├─ server/
│  │  ├─ package.json
├─ package.json
├─ tsconfig.json
├─ yarn.lock
```

## <a name="adding-the-first-scripts"></a>Adding the first script

Yarn workspace allows us to access any sub package through the `yarn workspace @my-app/*` command pattern, but typing the full command each time would become quite redundant. This is why, we can create a few helper script method that will ease our developer experience. Open the `package.json` at the root of the project and add the following `scripts` property to it.

```json
{
  "name": "my-app",
  "version": "1.0",
  "license": "UNLICENSED",
  "private": true,
  "workspaces": ["packages/*"],
  "devDependencies": {
    "typescript": "^4.2.3"
  },
  "scripts": {
    "app": "yarn workspace @my-app/app",
    "common": "yarn workspace @my-app/common",
    "server": "yarn workspace @my-app/server"
  }
}
```

You can now execute any command as if you were in the sub-package. For example, you could add some new dependencies by typing `yarn server add express`. This would add new dependencies to the `server` package directly.

In the next part we will start building our frontend and backend applications.

## <a name="preparing-for-git"></a>Preparing fot Git

If you plan to use Git as your version control tool, it is highly recommended to ignore generated files such a binaries or logs.

To do so, create a new file named `.gitignore` at the root of the project and copy the following content into it. This will ignore some files that will be generated later on in this tutorial and avoid commiting huge load of unnecessary data.

```gitignore
# Logs
yarn-debug.log*
yarn-error.log*

# Binaries
node_modules/

# Builds
dist/
**/public/script.js
```

Your folder structure should look like below:

```
my-app/
├─ packages/
├─ .gitignore
├─ package.json
```


The first part will guide you through the creation of the scafold of our application and setting up the environment using Yarn workspace and TypeScript.

Blog

Creating a web application using Yarn workspace, TypeScript, esbuild, React, and Express — advanced

Creating a web application using Yarn workspace, TypeScript, esbuild, React, and Express — part 3

Creating a web application using Yarn workspace, TypeScript, esbuild, React, and Express — part 2

Creating a web application using Yarn workspace, TypeScript, esbuild, React, and Express — part 1