ts-framework-cli

A minimalistic web framework for Typescript applications.

Installation

Start by installing the command line globally.

# Add to your dependencies using yarn
yarn global add "nxtep-io/ts-framework-cli";

# Or, using NPM
npm global install "github:nxtep-io/ts-framework-cli";

It will also work as a project dependency calling directly from node_modules or yarn run.

Getting Started

Generate a new project

Get started by generating a new TS Framework project using the built-in Yeoman generator:

ts-framework new app

After your project is created and all dependencies were installed, you can check its information directly from the typescript source, backed by ts-node runtime interpreter.

ts-framework info --development ./api/server.ts

#  --------------------------------------------------------------------------------
#                                                                                        
#              ts-framework                                                              
#              ============                                                              
#                                                                                        
#              Framework version:   nxtep-io/ts-framework#2.3.2                                       
#                                                                                        
#              App name:            ts-framework-cli                                          
#              App version:         2.4.4                                       
#              App port:            3000                             
#                                                                                        
#      
#      --------------------------------------------------------------------------------
#

Start the development server

To start coding into your project, use the development server, with file watching and live-reloading, backed by nodemon and ts-node.

ts-framework watch ./api/server.ts

Start the interactive console

The framework allows you to get into the instance and manipulate its components using a REPL interface, as an interactive console.

ts-framework console ./api/server.ts

Start the production server

Make sure you have the transpiled files from typescript ready before continuing.

yarn run tsc

Then, start the production server:

# Prepare same envs, if needed
export PORT=80;

# Start the production server
ts-framework start ./api/server.ts

Verbose and Inspection mode

You can run the command in verbose mode starting with the -vor --verbose flag. It is positional for the verbose mode to be also applied to the shell scripts, must the be first one.

ts-framework -V listen api/server.ts

To start the command in inspection mode (debug), you must pass the -i HOST:PORT or --inspect HOST:PORT flag. It is also positional, must be the second one when verbose is present. If not in verbose mode, it must be the first one.

# In regular mode
ts-framework --inspect 9229 listen api/server.ts

# In verbose mode
ts-framework -V --inspect 0.0.0.0:9229 listen api/server.ts

Note: The host may be ommitted for localhost, but in docker environments you may need to pass 0.0.0.0:PORT to make it work properly.

Running from docker

The command line has also an official docker image in the repository based on node:stretch. You may clone it and build locally to automate workflows in Docker environments.

docker build -t ts-framework .
docker run -it ts-framework --help

Or you may use it as a base image for your project deployments.

# Use as base image.
FROM ts-framework:latest

# Prepare node dependencies
WORKDIR /usr/src/my-app/
COPY ./package.json ./yarn.lock /usr/src/my-app/
RUN yarn install 

# Copy the app source code
COPY . /usr/src/my-app/

# Start container with ts-framework command
CMD ts-framework start api/server.ts

Debugging with VS Code and Docker

The watch command spins up a ts-node instance to execute Typescript code without a compilation step, and a nodemon instance to restart ts-node on source code changes. When inside a docker container, this combination can confuse the VS Code debugger. VS Code won't be able to locate the source code from the source maps, and many features will be disabled, like breakpoints.

You can manually add a source map path override to your VS Code's launch task, with

"sourceMapPathOverrides": {
    "/usr/src/myapp/*": "${workspaceFolder}/*"
},

Replace /usr/src/myapp with the container's source code path (Usually the argument of a WORKDIR call in the dockerfile).
Futher reading: microsoft/vscode-recipes#187

API Reference

The full library reference is available in the docs/ directory or published in nxtep-io.github.io/ts-framework-cli.

License

The project is licensed under the MIT License.