VS Code/TypeScript Start Template für Node.js und Web Applikationen

Funktioniert das Start Template aus dem Eintrag Visual Studio Code - TypeScript Start Templates (Let’s Code 24) noch? - Naja, nicht so recht, die Welt dreht sich weiter und die einzelnen Komponenten haben sich überholt, daher wird es Zeit die Bibliotheken upzudaten und den Vorgang zu modernisieren. Ein Start Template für die Programmierung mit TypeScript in Visual Studio Code (VS Code), sowohl für Node.js als auch für Web Applikationen. Wichtig dabei ist mir immer auch, dass man ein externes Modul einbindet, da dies zu Beginn häufig Schwierigkeiten macht. Die Start Templates dienen vor allem zum Erlernen der verwendeten Technologien, wie TypeScript, Node.js, Module Loader/Module Packer (WebPack). Es soll den Einstieg erleichtern und dadurch motivieren sich mehr mit TypeScript zu beschäftigen.

0. Wozu braucht man das?

Vor allem für die Web Entwicklung gibt es inzwischen viele Start Templates, die z.B. durch die CLIs (command line interface) der jeweiligen Frameworks, wie Angular oder Ionic, eine gute Basis für ein Projekt erstellen. Doch diese produzieren eine Menge Files und als Einsteiger ist man damit schnell überfordert. Man kommt damit schnell ins Tun und das ist sehr positiv. Auch ich verwende diese Templates zum Starten eines Projektes. Doch mir ist wichtig, dass man ein Grundverständnis für die verwendeten Technologien hat und dabei hilft dieses Start Template. Das Wissen hilft einem schließlich auch bei den komplexen Projekten, denn auch dort verwendet man dieselben Werkzeuge und Bibliotheken.

Ein anderer beliebter Ansatz zum Lernen von TypeScript ist die Verwendung von Online Editoren, die auf Knopfdruck kompilieren und eine Runtime Umgebung zur Verfügung stellen. Beispiele dafür sind: CodeSandbox, StackBlitz, Plunker, JSFiddle, Codepen, FiddleSalad, … Diese Services werden auch gerne dazu verwendet, Detailprobleme und/oder Lösungen zu zeigen. Das ist wirklich toll, aber versteckt eben den Aufbau der Projektumgebung, dieses Wissen fehlt dann manchmal und bei auftretenden Problemen hat man dann zu viel Respekt vor der komplexen Infrastruktur.

Als Zielgruppe sehe ich auch immer meine vielen Kollegen, die aus der Java oder .NET Welt kommen und mit einer Entwicklungsumgebung, wie Eclipse oder Visual Studio arbeiten. Sie sind den Komfort eines Projektfiles gewöhnt und vermissen das einfache Builden, Debuggen usw.

1. Schnellstart

Hat man den Artikel schon mal durchgearbeitet, will man nur mehr schnell ein Projekt starten, man hat schon alles nötige installiert usw.

1.1 Schnellstart - Node.js Applikation

git clone https://github.com/FranzHelm/starter-typescript2.git 
copy -r  .\starter-typescript2\starter-node-1\ nodeproj1\
cd nodeproj1\
npm install
code .

Build: Ctrl Shift B Debug: F5 Run: Ctrl + F5

1.2 Schnellstart - Web Applikation

git clone https://github.com/FranzHelm/starter-typescript2.git 
copy -r  .\starter-typescript2\starter-web-1\ webproj1\
cd webproj1\
npm install
code .

Achtung: In der aktuellen Version gibt es ein Problem, dass man den Namen im package.json gleich dem Verzeichnisnamen setzen muss (in unserem Beispiel also “name”: “webproj1”). Ansonsten sieht man Fehler bei npm install.

Server start:

npm start

Debug: F5

1.3 Schnellstart - mit Video

Diesen schnellen Einstieg (Node.js und Web Applikation) zeigt auch folgendes Video:

2. Verwendung der Start Templates

2.1 Vorbereitung

Folgende Werkzeuge müssen installiert werden:

a) Node.js

Node.js - Wir verwenden hier die LTS Version, aktuell: 10.15.3

b) Visual Studio Code (VS Code)

Visual Studio Code Man sollte die Windows Explorer Integration anhaken, dann hat man die Möglichkeit vom Windows Explorer - Kontextmenü (rechte Maustaste) einen Ordner oder eine Datei zu öffnen.

c) TypeScript

Durch die Installation von Node.js wurde der Node Package Manager (npm) installiert. Diesen verwenden wir nun, um uns die aktuelle TypeScript Version zu installieren.

PowerShell öffnen und mit folgendem Befehl TypeScript Compiler installieren:

npm install -g typescript Will man eine spezifische Version installieren: npm install -g typescript@3.4.5

Bei Problemen (timeout oder access denied Fehlermeldungen), liegt das häufig daran, dass man keinen direkten Zugriff zu GitHub hat, oft hilft eine proxy Einstellung. (Siehe Artikel: Proxy Settings für npm, Angular CLI, …)

2.2 Das Start Template downloaden

Dies ist für beide Varianten: Node.js und Web Applikationen nötig.

Download:

Um möglichst wenige Vorkenntnisse vorauszusetzen, holen wir uns das Paket als gezippten Download und entzippen es. https://github.com/FranzHelm/starter-typescript2/archive/master.zip

Das Projekt enthält zwei Tamplates:

starter-node-1: TypeScript Node.js Sarter Project
starter-web-1: TypeScript Web App Starter Projekt

Alternativ via Git auschecken:

Hat man git installiert, kann man natürlich das Paket auch über die command-line auschecken:

git clone https://github.com/FranzHelm/starter-typescript2.git

Anmerkung:

Ich verwende bewusst kein Werkzeug (scaffolding tool/Source-Gerüstwerkzeug), das eine Projektinfrastruktur aufbaut, wie Yeoman um es möglichst simpel zu halten.

2.3 Node.js Applikation

Eignet sich hervorragend um TypeScript zu lernen. Als JavaScript Runtime verwendet man nicht den Browser, sondern Node.js, das oft in Web Servern zum Einsatz kommt oder auch als Runtime für Command-line Tools.

2019-05-04-17_56_47-utils.ts---nodeproj1---Visual-Studio-Code

Via Windows Explorer den Ordner starter-node-1 vom StarterTemplate (starter-typescript2\starter-node-1) an eine beliebige Stelle kopieren und am besten auch umbenennen. Das ist dann der Projektname.

Anschließend diesen Ordner mit VS Code öffnen. Rechte Maustaste auf den Ordner Open with Code.

In Visual Studio öffnen wir ein Terminal, die PowerShell (Strg + ö) um die npm packages zu installieren, die im File package.js definiert sind.

npm install

Builden:

Ctrl Shift B

Debuggen, bzw. Starten mit

F5
Ctrl + F5

2.4 Web Applikation

Eine Web Applikation muss in einem Server gehostet werden. Deshalb benötigen wir einen kleinen Webserver, der das kompilierte JavaScript ausliefern kann und natürlich auch html und css Files. Dazu gibt es viele Möglichkeiten ich zeige hier eine ganz einfache.

2019-05-04-18_01_59-utils.ts---webproj1---Visual-Studio-Code

Anschließend diesen Ordner mit VS Code öffnen. Rechte Maustaste auf den Ordner Open with Code.

In Visual Studio öffnen wir ein Terminal, die PowerShell (Strg + ö) um die npm packages zu installieren, die im File package.js definiert sind.

npm install

Wir benötigen also noch den Google Web Browser Chrome. Und in Visual Studio Code die Extension Debugger for Chrome: (am einfachsten innerhalb VS Code unter Extensions nach “Debugger for Chrome” suchen.)

Um den Server zu starten, es öffnet sich auch ein Browserfenster:

npm start

Debuggen:

Man kann sowohl im Browser debuggen, als auch, mit F5 innerhalb Visual Studio Code, dazu einen Breakpoint in einem ts File setzen und mit F5 starten (Chrome öffnet sich).

3. Bemerkungen zu Templateaufbau

Die Anforderung an mein kleines TypeScript Projekttemplate, hat sich nicht geändert. Das Template dient mir als Ausgangsbasis für TypeScript/JavaScript Projekte. Es soll folgendes aufzeigen:

Wie man eine Klasse in einem eigenen TypeScript File einbindet.
Wie man eine externe library einbindet (inkl. type declarations).
Wie man mit Visual Studio Code bequem arbeiten kann (Builden, Debuggen).

3.1 Node.js Applikation

Vergleicht man die alte (v1.0) Version mit der neuen (v2.2), dann sieht man, dass sich im Node.js Template kaum was verändert hat.

 git clone --branch v1.0 https://github.com/FranzHelm/starter-typescript2.git starter-typescript2-v1.0
 git clone --branch v2.2 https://github.com/FranzHelm/starter-typescript2.git starter-typescript2-v2.2

Als Output Folder verwende ich jetzt hier ebenfalls den dist Folder, wie in der Web Applikation.

Im utils.ts sieht man noch, dass für lodash inzwischen auch folgendes funktioniert: import _ from “lodash”;
statt wie vorher nötig: import * as _ from “lodash”;

Das tsconfig file ist nun viel größer, weil die auskommentierten Einträge, die bei tsc ini erzeugt werden, nicht mehr entfernt wurden.

3.2 Web Applikation - WebPack

Es ist nicht mehr üblich jedes JavaScript File in der Html Datei einzubinden, sondern man verwendet Module-Loader, wie SystemJS, RequireJS. ECMAScript 6 (bzw. dies wurde umbenannt in ECMAScript 2015) und nachfolgende Versionen haben einen Module Loader inkludiert, doch viele externe Libraries unterstützen das Format noch nicht und aus Performancegründen ist es auch besser, den Code inklusive der externen Libraries in wenige Files zu bündeln.

Bundlingtools, auch module bundler, bzw. Modul Packer genannt, gibt es wieder einige: Webpack, Rollup, Parcel, Browserify, Bazel, … Am meisten verbreitet scheint im Moment WebPack zu sein, daher war es mir wichtig diesen nun einzusetzen. Angular verwendet meiner Meinung nach zurzeit ebenfalls WebPack, wird aber in Zukunft das konfigurierbarer machen und wohl eher in Richtung Bazel (von Google) gehen.

Anmerkung: Gegenüber dem v1.0 Template habe ich den module loader SystemJS durch WebPack ersetzt. Den WebServer lite-server habe ich allerdings belassen. WebPack hat selbst einen Server webpack-dev-server, doch durch die Konfiguration wird das webpack.config File gleich ein wenig komplexer und das wollte ich vorerst verhindern. Der lite-server, kommt so wie wir ihn hier verwenden ohne Konfigurationsfile aus.

Was hat sich geändert:

Auf das Inkludieren des shim Files (polyfill oder wie auch immer man das zurzeit nennt), das für ältere Browser nötig ist, wurde verzichtet. Man muss überprüfen, ob es für die unterstützen Browser Probleme gibt.

WebPack wurde so konfiguriert, dass es nur ein File generiert, auch lodash wird also in das file bundle.js eingefügt, dadurch vereinfacht sich das einbetten im html File auf folgende Zeile:

 <script src="./dist/bundle.js"></script>

Im package.json sieht man unter scripts, dass der TypeScript Compiler nicht aufgerufen wird, sondern nur das webpack cli. Im Konfigurationsfile von Webpack erkennt man, dass ts-loader eingebunden ist, dieser übernimmt das Kompilieren des Codes, indem er natürlich auf den TypeScript Compiler zurrückgreift.

4. Anhang

4.1 Aktuelle Versionen:

> git --version
git version 2.21.0.windows.1
>tsc --version
Version 3.4.5
>npm --version
6.4.1
>node --version
v10.15.3
>code --version
1.33.1

Zum einfachen Kopieren in die PowerShell, hier nochmals nur die Befehle aufgelistet:

git --version
tsc --version
npm --version
node --version
code --version

4.2 Parcel

Im Zuge des Erstellens dieses Artikels bin ich das erste Mal an den module bundler Parcel gestoßen, er ermöglicht einen sehr einfachen Start.

npm install -g parcel-bundler

b) Web Applikation mit Parcel starten

Kopiere aus dem starter-web-1 nur die index.html und den app Ordner.

Ersetze im index.html folgende Zeile:

 <script src="./dist/bundle.js"></script>

durch:

 <script src="./app/main.ts"></script>

Nun im Terminal ohne vorher npm install aufzurufen, einfach Folgendes eintippen:

parcel index.html

Die nötigen npm Packages werden dazugefügt, kompiliert und paketiert und ein Webserver gestartet. Der Vorgang reagiert auch, wenn man in den TypeScript Files etwas ändert (watch mode).

Damit auch Debuggen in VS Code funktionieren würde, muss man sich noch damit beschäftigen, wie man die sourceMaps aktiviert, …

b) Node.js Applikation mit Parcel starten

Das index.html ist natürlich nicht nötig und kann gelöscht werden, man ruft einfach foglendes auf:

parcel index.ts --target=node

Starten:

node dist/index.js

Eigentlich braucht man so meine Start Templates nicht mehr, doch meine Intension ist ja, dass man die üblicherweise eingesetzten Tools und Vorgehensweisen versteht.