Tools such as Swagger, JSON Schema, or OpenAPI are powerful, but they can be verbose, inflexible, or not conducive to reuse.

Well, I recently discovered TypeSpec. In this guide, I’ll show you how to take advantage of TypeSpec to create modern, maintainable, and well-documented REST APIs.

We'll take a look at:

• Prerequisites

• What is TypeSpec?

• Why use TypeSpec?

• How to Install and Configure TypeSpec

• TypeSpec Basic Syntax

• How to Create a REST API Model

• How to Build the API in Express and ASP.NET Core

• Best Practices for Structuring TypeSpec Projects and Components

• Conclusion

Prerequisites

Before we dive into using TypeSpec to document and model APIs, here are a few things you'll need to familiarize yourself with and/or have:

• Node.js (version 18 or higher)

• npm for dependency management

• Visual Studio Code (recommended to take advantage of the official TypeSpec extension). For an optimal experience, to create your project easily, it provides syntax highlighting, validation, autocompletion, navigation, and more.

• TypeSpec Extension in VS Code (You can install the extension via Visual Studio Marketplace)

• An understanding of how to use and create APIs

What is TypeSpec?

TypeSpec is an open-source declarative language, developed by Microsoft, designed to describe APIs in an explicit, reusable, scalable, and standards-based way. It’s designed to model REST, gRPC, GraphQL, and other types of APIs, and offers a modern syntax close to TypeScript.

It can automatically generate:

• OpenAPI, JSON Schema, or Protobuf specifications

• server and client code

• API documentation

• and other interface-related artifacts

TypeSpec isn't just a language – it's an API design platform that favors abstraction, encourages code reuse, and integrates with modern tools like Visual Studio Code via a dedicated extension. You can install the extension via the VS Code Visual Studio Marketplace.

Why use TypeSpec?

Before diving into the code, let's take a minute to understand the TypeSpec philosophy. Microsoft uses TypeSpec internally to deliver high-quality API services to millions of customers, across tens of thousands of endpoints, while ensuring code quality, governance, and scalability.

Unlike generators such as Swagger, Codegen, or Postman, which start from an OpenAPI file to generate code, TypeSpec does the opposite: you first write your API design in a DSL (Domain Specific Language), then generate everything you need.

TypeSpec has been designed to meet the major challenges of large-scale API design and governance:

• Simplification: clear, concise syntax to focus on business logic.

• Reusability: encapsulates types, request/response models, and directives in modular components.

• Productivity: automatically generates the necessary resources from a single source definition.

• Consistency: maintains compliance with internal standards thanks to shared libraries.

• Interoperability: integrates with the OpenAPI ecosystem and supports multi-format generation.

• Scalability: designed to handle thousands of endpoints like those used by Microsoft Azure.

Let's take a look at how to install and configure the development environment

How to Install and Configure TypeSpec

Before you can start writing your first API with TypeSpec, you need to set up your development environment. Here's how to install TypeSpec on your machine.

Requirements:

• Node.js (version 18 or higher)

• npm for dependency management

• Visual Studio Code (recommended to take advantage of the official TypeSpec extension). For an optimal experience, it provides syntax highlighting, validation, autocompletion, navigation, and more.

TypeSpec CLI global installation:

npm install -g @typespec/compiler

How to Create a TypeSpec Project

The easiest way to create a project is to use Visual Studio Code via the TypeSpec extension you've installed (if you're not comfortable with the command line (CMD)).

Create a folder containing the project and open it with Visual Studio Code. Then click on the View tab, and next on Comment Palette .

In the search bar that appears, enter TypeSpec: Create TypeSpec Project.

Follow the quick selections to select the root folder of the project you've just created. Then choose the Template – for our case this will be Generic REST API – and enter the project name. Leave the emitter OpenAPI 3.1 document (3.1 is the current version at the time of writing) selected by default. This will put us @typespec/http@typespec/openapi3. Finally, wait for the project configuration to finish.

You should have a basic TypeSpec project configuration with a structure that looks like this:

• node_modules/: Directory where npm installs project dependencies.

• main.tsp: the entry point for your TypeSpec build. This file generally contains the main definitions of your models, services, and operations.

• package.json: Contains project metadata, including dependencies, scripts, and other project-related information.

• tspconfig.yaml: TypeSpec compiler configuration file, specifying options and parameters for the generation process.

You can also run tsp compile . to compile the project, but it's better to run tsp compile . --watch to automatically compile changes during development each time you save.

Once the project has been compiled, you'll see the tsp-output and schema folders generated and a file added openai.yaml.

• tsp-output/: Directory where the TypeSpec compiler generates files.

• openapi.yaml: OpenAPI specification file generated for your API, detailing API endpoints, templates, and operations. Output may vary depending on the target format specified in the tspconfig.yaml file.

emit:
  - "@typespec/openapi3"
options:
  "@typespec/openapi3":
    emitter-output-dir: "{output-dir}/schema"
    openapi-versions:
      - 3.1.0

Thanks to this configuration of the tspconfig.yaml file, one of TypeSpec's major assets is its ability to automatically generate OpenAPI specifications from clear, typed, and modular source code. This means you can write your API as you would in TypeScript (or a well-structured DSL), and get output in .yaml files compatible with the whole OpenAPI ecosystem: Swagger UI, Postman, Redoc, and so on.

In the next section, we'll look at the basic syntax of TypeSpec.

TypeSpec Basic Syntax

Now that you've got a clear idea of what TypeSpec is and what its benefits are in the world of API design, it's time to get to the heart of the matter: the basic syntax.

TypeSpec is a declarative language, inspired by TypeScript, that lets you model the resources, routes, data structures, and behaviors of an API in an explicit, readable, and modular way. Its syntax is based on simple keywords and clear file organization, making it easy to learn yet powerful.

Language Basics

Here's a very simple example of defining a model with TypeSpec:

model Book {
  id: string;
  title: string;
  author: string;
}

This block defines a Book resource with three typed fields. The model keyword is used to describe the JSON objects manipulated by the API. It is equivalent to schemas in JSON Schema or type definitions in OpenAPI.

Defining an HTTP operation

TypeSpec lets you bind operations to models using the @route keyword. Here's a minimal example of an endpoint:

@route("/books")
op listBooks(): Book[];

This syntax declares a REST operation that returns a list of books. @route indicates the URL path, op introduces an operation, and Book[] is the return type.

You can also define path, query, or body parameters very easily.

@route("/books/{id}")
op getBook(@path id: string): Book;

In this example, we declare that id is a URL parameter (path parameter).

Fundamental Concepts

model Defining data structures

A model represents an API entity, like a JSON object. Models are the basis of your information exchanges.

model User {
  id: string;
  email: string;
  age?: int32;
}

interface Group operations

An interface groups together a set of logically linked operations. This is useful for structuring large API sets.

interface BookOperations {
  @get op listBooks(): Book[];
  @get op getBook(@path id: string): Book;
}

service Entry point of the API

A service defines publicly exposed interfaces, their version, and the basic path.

@service({ title: "Book API", version: "1.0.0" })
namespace BookApi {
  interface BookOperations;
}

Import and Organize Your Code with Namespaces

TypeSpec provides clear organization through namespaces, similar to modules or packages.

namespace CommonModels {
  model Error {
    message: string;
  }
}

Then you can import them into another file like this:

import CommonModels from "./common.tsp";

Complete Example of a REST Service

Let's take a complete example of a REST service in TypeSpec.

@service({ title: "Book Service", version: "1.0.0" })

@route("/books")

namespace BookService {

  model Book {
    id: string;
    title: string;
    author: string;
    publishedYear?: int32;
  }

  @get()
  op listBooks(): Book[];

  @post()
  op createBook(@body book: Book): Book;

  @get("/{id}")
  op getBook(@path id: string): Book;

  @put("/{id}")
  op updateBook(@path id: string, @body book: Book): Book;

  @delete("/{id}")
  op deleteBook(@path id: string): void;
}

Here’s what’s going on:

• @service({ title, version }): Defines service metadata (name, version), useful for generated documentation (for example, Swagger UI).

• @route("/books"): Defines the basic path for all operations of this API.

• namespace BookService { ... }: Encapsulates all models and operations linked to this service under a single logical name.

Next come the operations:

• @get() op listBooks(): Endpoint GET /books qui retourne un tableau de livres.

• @post() op createBook(): Endpoint POST /books which accepts a Book object in the request body (@body) and returns the created book.

• @get("/{id}"): Endpoint GET /books/{id} which retrieves a book via its identifier (@path).

• @put("/{id}"): Endpoint PUT /books/{id} which updates a book's data.

• @delete("/{id}"): Deletes a book via its id. The void type means that no data is returned.

With just a few lines, you get a complete, well-organized, easily readable REST service, ready to be automatically converted into OpenAPI documentation, a client SDK, or backend code.

Add Validation Annotations

TypeSpec makes it easy to add validation annotations to your models using:

model Book {
  id: string;
  title: string @minLength(3);
  author: string @minLength(3);
  publishedYear?: int32 @minValue(1800);
}

This adds validation rules directly to the schema, which will be taken into account during OpenAPI generation.

Comparison with Other Tools (OpenAPI / Swagger)

So you might wonder – why should you use TypeSpec rather than writing directly in OpenAPI?

Let's take the example of OpenAPI 3 (YAML):

paths:
  /books:
    get:
      summary: Get list of books
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
    post:
      summary: Create a new book
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Book'
      responses:
        '201':
          description: Created
  /books/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
    put:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Book'
    delete:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer

As you can see, the OpenAPI definition is much more verbose. Relationships between paths, methods, schemas, and parameters are scattered, which complicates reading and maintenance. Also, it's less typed, given that OpenAPI remains YAML (or JSON), without the typing security or modularity of a real language.

Why TypeSpec is useful here

With TypeSpec, everything is centralized in a declarative, modular, typed, and intuitive format.

• Greater legibility: less noise, more intent.

• Reusability: you can create modular components and share them between projects.

• Productivity: you write less code and generate more (OpenAPI, client, server, doc).

• Consistency: errors are detected early thanks to strong typing.

Note: TypeSpec doesn't replace OpenAPI, but complements it: you write to TypeSpec, then automatically generate OpenAPI files, SDKs, specs and so on. It gives you a source language for accurately describing your API.

In the next section, we'll look at how to create a REST API template.

How to Create a REST API Model

To deepen our understanding of REST API creation with TypeSpec, let's continue with the example of managing books. In this example, we'll create a Book model, define a service to manage the books, and add validations to ensure that the data respects the right constraints.

Define a Data Model for Book

First, we'll define a data model for the Book resource. A book can have the following properties:

• id: A unique identifier for the book.

• title: The title of the book.

• author: The author of the book.

• publicationYear: The book's year of publication.

• isbn: The book's ISBN number.

Book model in TypeSpec

model Book {
  id: integer;
  @minLength(1)
  title: string;
  @minLength(1)
  author: string;
  publicationYear: integer;
  @pattern("^\\d{3}-\\d{1,5}-\\d{1,7}-\\d{1,7}-\\d{1}$")
  isbn: string;
}

• id: Unique book identifier (integer type).

• title and author: Character strings representing the book's title and author, validated by @minLength(1) to ensure they are not empty.

• publicationYear: The book's year of publication (integer type).

• isbn: The book's ISBN number, validated with a regular expression that matches the standard format of an ISBN.

Define a REST Service to Manage Books

Now that we have a Book model, we'll create a service to manage CRUD operations on this resource. This service will contain methods for retrieving a book by its identifier, creating a new book, updating an existing book, and deleting a book.

BooksService service in TypeSpec

service BooksService {

  @get("/books/{id}")
  getBook(id: integer): Book;

  @post("/books")
  createBook(book: Book): Book;

  @put("/books/{id}")
  updateBook(id: integer, book: Book): Book;

  @delete("/books/{id}")
  deleteBook(id: integer): void;
}

The BooksService contains four methods for performing actions on books:

• @get("/books/{id}"): Method for retrieving a book by its id.

• @post("/books"): Method for creating a new book.

• @put("/books/{id}"): Method for updating an existing book by its id.

• @delete("/books/{id}"): Method for deleting a book based on its id.

These methods use HTTP annotations to indicate the type of operation they perform (GET, POST, PUT, DELETE).

Add Additional Validations for the Book Model

As in the previous example for users, we can add additional validations on Book template properties.

Example of validation on publicationYear and isbn

model Book {
  id: integer;
  @minLength(1)
  title: string;
  @minLength(1)
  author: string;
  @minValue(1000)
  publicationYear: integer;
  @pattern("^\\d{3}-\\d{1,5}-\\d{1,7}-\\d{1,7}-\\d{1}$")
  isbn: string;
}

• @minValue(1000) guarantees that the year of publication is greater than or equal to 1000.

• Validation of the isbn remains the same, using a regular expression to validate a standard ISBN format.

A Complete Service for Managing Books

Now that we have the Book model and the necessary validations, here's a complete service for managing books, with all the essential operations.

Complete BooksService in TypeSpec

model Book {
  id: integer;
  @minLength(1)
  title: string;
  @minLength(1)
  author: string;
  @minValue(1000)
  publicationYear: integer;
  @pattern("^\\d{3}-\\d{1,5}-\\d{1,7}-\\d{1,7}-\\d{1}$")
  isbn: string;
}

service BooksService {
  @get("/books/{id}")
  getBook(id: integer): Book;

  @post("/books")
  createBook(book: Book): Book;

  @put("/books/{id}")
  updateBook(id: integer, book: Book): Book;

  @delete("/books/{id}")
  deleteBook(id: integer): void;
}

• The Book model defines properties and validations for a book.

• The BooksService provides endpoints for retrieving, creating, updating, and deleting a book.

• Each service method is correctly annotated with the corresponding HTTP verbs (GET, POST, PUT, DELETE).

And here’s a summary of everything we’ve done:

• We created a Book model with properties such as title, author, year of publication, and ISBN number.

• We defined a BooksService to provide CRUD operations on books.

• We added validations to ensure that the data respected specified constraints (for example, ISBN and year of publication).

• We designed a complete REST API to manage books with TypeSpec, using a minimum amount of code and staying true to standards.

This example shows just how quickly and efficiently TypeSpec can be used to model a REST API, while ensuring a clear structure and robust validations.

How to Build the API in Express and ASP.NET Core

Now that we've defined a book management REST service with TypeSpec, let's see how we'd implement this same API using two popular frameworks:

• ExpressJS (Node.js / TypeScript)

• ASP.NET Core (C#)

This will allow us to better compare TypeSpec's conciseness and readability with traditional implementations.

Manual implementation with ExpressJS (Node.js / TypeScript):

//server.ts
import express from 'express';

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

interface Book {
  id: number;
  title: string;
  author: string;
  publicationYear: number;
  isbn: string;
}

const books: Book[] = [];

// GET /books/:id
app.get('/books/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const book = books.find(b => b.id === id);
  if (!book) return res.status(404).send({ message: 'Book not found' });
  res.send(book);
});

// POST /books
app.post('/books', (req, res) => {
  const newBook: Book = req.body;
  books.push(newBook);
  res.status(201).send(newBook);
});

// PUT /books/:id
app.put('/books/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const index = books.findIndex(b => b.id === id);
  if (index === -1) return res.status(404).send({ message: 'Book not found' });

  books[index] = req.body;
  res.send(books[index]);
});

// DELETE /books/:id
app.delete('/books/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const index = books.findIndex(b => b.id === id);
  if (index === -1) return res.status(404).send({ message: 'Book not found' });

  books.splice(index, 1);
  res.status(204).send();
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Observations:

• A lot of repetitive logic.

• No automatic validation.

• Routes must be maintained manually.

• No automatically generated API documentation.

Manual implementation with ASP.NET Core (C#):

// Book.cs
public class Book
{
    public int Id { get; set; }

    [Required]
    public string Title { get; set; } = string.Empty;

    [Required]
    public string Author { get; set; } = string.Empty;

    [Range(1000, int.MaxValue)]
    public int PublicationYear { get; set; }

    [RegularExpression(@"^\d{3}-\d{1,5}-\d{1,7}-\d{1,7}-\d{1}$")]
    public string Isbn { get; set; } = string.Empty;
}

// BooksController.cs
[ApiController]
[Route("books")]
public class BooksController : ControllerBase
{
    private static readonly List<Book> books = new();

    [HttpGet("{id}")]
    public IActionResult GetBook(int id)
    {
        var book = books.FirstOrDefault(b => b.Id == id);
        if (book == null) return NotFound("Book not found");
        return Ok(book);
    }

    [HttpPost]
    public IActionResult CreateBook([FromBody] Book book)
    {
        books.Add(book);
        return CreatedAtAction(nameof(GetBook), new { id = book.Id }, book);
    }

    [HttpPut("{id}")]
    public IActionResult UpdateBook(int id, [FromBody] Book updatedBook)
    {
        var index = books.FindIndex(b => b.Id == id);
        if (index == -1) return NotFound("Book not found");

        books[index] = updatedBook;
        return Ok(updatedBook);
    }

    [HttpDelete("{id}")]
    public IActionResult DeleteBook(int id)
    {
        var book = books.FirstOrDefault(b => b.Id == id);
        if (book == null) return NotFound("Book not found");

        books.Remove(book);
        return NoContent();
    }
}

Observations:

• More formal and structured than Express, thanks to C# annotations ([HttpPost], [Required], and so on).

• Validation is handled automatically via Data Annotations.

• Once again, no automatic OpenAPI generation or SDK client without additional configuration.

Comparison with TypeSpec:

Best Practices for Structuring TypeSpec Projects and Components

When you start writing API definitions in TypeSpec, it's easy to put everything in a single file. But as with any software project, as the application grows, a good structure becomes essential to guarantee the readability, reusability and maintainability of the code.

Here's a set of best practices I strongly recommend:

Organize by Functional Area

Use namespaces to group models, interfaces, and operations by business domain: book, user, auth, payment, and so on.

namespace MyApi.Books;

Create a /books folder with the following files:

src/
├── books/
│   ├── models.tsp
│   ├── routes.tsp
│   └── service.tsp

This ensures a clear separation of responsibilities, just like in a well-structured Node.js project.

A Single main.tsp Entry Point

This is the main file that orchestrates:

// main.tsp
import "./books/service.tsp";
import "./users/service.tsp";
import "./auth/service.tsp";

This allows you to compile the entire project from a single point.

Create Reusable Components

Define common models and types in a shared file. Example:

// common/models.tsp
model ErrorResponse {
  code: string;
  message: string;
}

@defaultResponse
op Error(): ErrorResponse;

Then import them into your other files:

import "../common/models.tsp";

This is handy for centralizing errors, standard answers, pagination types, and so on.

Use Decorators to Enrich Your Components

Decorators such as @doc, @minLength, @server, @route or @tag can be used to generate valid, documented APIs without any extra effort:

@route("/books")
@doc("Get all books")
op listBooks(): Book[];

A well-annotated API is one that is ready for automatic generation of documentation or clients.

Define Servers in the Right Place

Add your @server directive to a service.tsp or global api.tsp file:

@server("Production", "https://api.mysite.com")
@server("Staging", "https://staging.mysite.com")

This allows you to target different environments without duplicating definitions.

Validate Regularly

Integrate tsp compile into your CI/CD to ensure that your definitions are always valid. Example with an npm script:

npm run tsp compile src/main.tsp --emit=./dist

This avoids last-minute errors and guarantees the consistency of your API over time.

Example of a recommended complete structure:

project-root/
├── src/
│   ├── books/
│   │   ├── models.tsp
│   │   ├── routes.tsp
│   │   └── service.tsp
│   ├── users/
│   │   ├── models.tsp
│   │   └── service.tsp
│   ├── common/
│   │   └── models.tsp
│   └── main.tsp
├── tspconfig.yaml
├── package.json
└── README.md

In summary:

Conclusion

TypeSpec represents a real evolution in the way we design, document and maintain APIs. By adopting a declarative, modular, and typed approach, it simplifies the definition of APIs while enhancing their quality, readability, and consistency on a large scale.

Whether you're a front-end developer consuming APIs, a software architect looking to standardize your team's practices, or a technical documentation enthusiast, TypeSpec offers you a robust, modern, and extensible solution.

The TypeSpec ecosystem is still young but very promising, supported by Microsoft and used internally on a large scale. So now's the time to start exploring and adopting it for your projects.

Ressources

1. TypeSpec official website
   https://typespec.io
   Full documentation, guides, syntax references and APIs.

2. TypeSpec GitHub repository (Microsoft)
   https://github.com/microsoft/typespec
   Source code, examples and community discussions.

3. Playground TypeSpec (essayer dans le navigateur)
   https://typespec.io/playground
   Quickly test your models without installing anything.

4. TypeSpec documentation — Microsoft Learn
   https://learn.microsoft.com/en-us/azure/developer/typespec/overview
   Learn how to use TypeSpec to create consistent, high-quality APIs efficiently and integrate them seamlessly with existing toolchains.

5. OpenAPI Specification
   https://swagger.io/specification
   To compare with current API description standards.

6. TypeSpec 101 by Mario Guerra Product Manager for TypeSpec at Microsoft
   https://www.youtube.com/playlist?list=PLYWCCsom5Txglkl_I1XvwzrzM5G3SuVsR
   A tutorial series, hosted by Mario Guerra, TypeSpec product manager at Microsoft, will guide you through the process of building a REST API using TypeSpec, and generating an OpenAPI specification from our code.

7. APIs at Scale with TypeSpec
   https://youtu.be/yfCYrKaojDo
   A talk given by Mandy Whaley from Microsoft at the 2024 Austin API Summit in Austin, Texas.

Thanks for reading. You can find me on LinkedIn, and follow me on all socials @AdalbertPungu.

If you're not familiar with TypeScript, you can read through this comprehensive beginner's guide to get started. If you do know some TS, that's great – I'll discuss why it's recommended in most projects that use JavaScript.

TypeScript Logo

What is TypeScript?

TypeScript is a superset of JavaScript. This means you can use all the useful JavaScript features you already know and love, along with some others that TypeScript adds that didn't exist before.

In other words, TypeScript offers all the JavaScript functionality plus an extra layer, which is the TypeScript type system.

TypeScript addresses many of JavaScript's limitations that other languages have tackled to help produce complex applications.

With TypeScript, you can run your code anywhere and on any platform, browser or hosted. This is because these tools are multi-platform, which means you can develop TypeScript applications using Windows, Mac, or Linux.

Windows - unsplash

Microsoft developed TypeScript to meet the challenges of modern web development. It provides static type checking along with many productivity-enhancing features. It also aligns with the rapid evolution of ECMAScript.

Some of TypeScript's most useful features are its types, annotations, interfaces, classes, encapsulation of your logic, and data with access modifiers. You can also take advantage of productivity enhancements such as variable and property renaming. All this helps you more easily find errors in your code before executing it.

What Makes TypeScript So Successful?

TypeScript fills a gap in the world of web development, offering a versatile, high-performance solution to help you build scalable, high-quality web applications.

TypeScript was first announced in October 2012. Since then it has grown rapidly and steadily, becoming a popular solution for web development and application development in general.

TS adds a variety of useful tools and syntax to an already mature language, bringing the power and productivity of open source object-oriented development to a fully compatible core of JavaScript.

Here are some of the advantages that have made TypeScript so successful and a better choice for web development:

• TypeScript is a superset of JavaScript, meaning that all existing JavaScript code is valid in TypeScript. Developers can gradually migrate their JavaScript code to TypeScript without disrupting their workflow.

• TypeScript offers static type checking, which means that developers can detect typing errors early in the development phase. This significantly reduces type-related bugs and improves code stability and reliability.

• Thanks to its static typing system, TypeScript provides editor assistance, an autocomplete feature, and better documentation. This makes development easier and accelerates developer productivity.

• Thanks to static type checking, many errors that would normally occur at runtime in JavaScript are detected at the development stage, reducing debugging time and effort.

• TypeScript benefits from an active and constantly growing community of developers, as well as regular support and frequent updates from Microsoft, which continues to perfect this technology.

Thanks to these benefits, TypeScript has gained in popularity and is a solid choice for modern web development. Its ability to improve code quality, facilitate smooth development, and deliver a better overall experience has contributed to its success in the web development ecosystem.

Using TypeScript with Other Technologies

TypeScript integrates seamlessly with other popular technologies and frameworks such as React, Angular, Vue.js and Node.js. This compatibility makes it a natural choice for developers working in these ecosystems.

TypeScript also encourages better code organization through the use of interfaces, classes, and modules. This facilitates code maintenance and readability, especially when managing complex projects.

TypeScript and Angular

Google's Angular caught everyone's attention when it decided to use TypeScript as its primary programming language from the start of its development in September 2014.

The Angular development team announced this change at ng-conf in October 2014, where they presented Angular 2 (the major version of AngularJS) based on TypeScript.

Let's look at an example of some Angular code before the introduction of TypeScript:

// Angular Component in JavaScript (ES5)
angular.module('app').component('appRoot', {
    templateUrl: './app.component.html',
    controller: function () {
        this.message = "Hello, JavaScript and Angular!";
    }
});

Here's what's going on and what to note:

* **AngularJS Syntax**: Before the arrival of Angular 2, Angular used JavaScript (ES5) syntax. In the above example, we're using `angular.module` to define a module, and `component` to define a component.
* **Controller**: In AngularJS, a controller is used to manage the logic of a component. In the example above, the controller function defines the property `this.message`.
* **TemplateUrl**: The HTML template is defined via the `templateUrl` property in the component configuration. In this example, it's supposed to be in the file `'./app.component.html'`.

And here's what the same Angular component would look like after the introduction of TypeScript:

```code
// Angular Component in TypeScript
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    message: string = "Hello, TypeScript and Angular!";
}

It's important to note that the switch from JavaScript to TypeScript in Angular has brought several benefits, including:

• Strong typing: TypeScript lets you specify variable types, making code safer and less error-prone.

• Better Intellisense: The code editor can provide suggestions and type information in real time, improving developer productivity.

• Early error detection: TypeScript can detect compiler errors before runtime, making debugging easier and reducing runtime errors.

• Better maintainability: Type annotations and code structure make code easier to read and maintain.

Angular switched to TypeScript because of several factors, including TypeScript's static type checking, which solved many of the typing problems encountered in AngularJS (the previous version of Angular).

TS also offered advantages in terms of complex project management, productivity, compatibility with JavaScript and active support from Microsoft.

TypeScript also offered developers greater productivity thanks to its advanced development support features, such as autocompletion, code navigation, and early error detection. This has enabled Angular to establish itself as a robust web development framework appreciated by many developers and companies.

Angular has continued to evolve using TypeScript as its core language, and the combination of Angular and TypeScript has become a common choice for the development of modern web applications.

This has also helped to strengthen TypeScript's adoption among the developer community, making it one of the most popular languages for web development.

How to Configure TypeScript for Use in Existing JavaScript Projects

Angular is already based on TypeScript, so there's no need to convert JavaScript to TypeScript in your modern Angular projects.

But if you use JavaScript in your TypeScript files, it will be less strict in its type checks. So, when integrating TypeScript into your existing JavaScript-based projects, it's important to make a gradual transition, set up tsconfig.json, manage types carefully, and test regularly.

How to Use TypeScript with Node.js:

As your development needs grow with your team, you may need more powerful tools and syntax when working with Node.js.

This is where using TypeScript with Node.js can be a good approach – and it lets you take adtvantage of TS's static type checking, as well as support for the latest JavaScript features.

The first thing to do is install or add TypeScript to the project like this:

npm install --save-dev typescript

Create a TypeScript configuration file (tsconfig.json) manually at the root of the project or by running the command below, which will generate it automatically.

npx tsc --init

Modify the tsconfig.json file to specify the necessary compilation parameters and configure the paths to existing JavaScript files.

This is an example of the TypeScript configuration file (tsconfig.json):

{
  "compilerOptions": {
    "target": "ES2020",              // Target JavaScript version
    "module": "CommonJS",            // Module system to use
    "outDir": "./dist",              // Output directory for compiled files
    "rootDir": "./src",              // Source directory for TypeScript files
    "strict": true,                  // Enable strict type checking
    "esModuleInterop": true,         // Enable ES6 module interop
    "forceConsistentCasingInFileNames": true, // Check consistent file casing
    "declaration": true,            // Generate declaration files (.d.ts)
    "sourceMap": true               // Generate source map files (.js.map)
  },
  "include": ["src/**/*.ts"],       // Files to include in compilation
  "exclude": ["node_modules"]       // Files to exclude from compilation
}

Don't forget to place the tsconfig.json file at the root of your project if you've done this manually. Then be sure to adjust the values of the options according to your project's needs, such as source directory (rootDir), output directory (outDir), "target", "module" options, etc.

After doing this you'll be ready to use TypeScript in your Node projects.

How to Use TypeScript with React:

TypeScript offers developers a more structured approach to JavaScript application development, and is a natural fit for the processes that most React developers already use.

Combining React's component-based approach with TypeScript's discipline allows you to create clean web applications that will be easier to maintain over time.

React has various tools at its disposal, such as accessory types and flow, but if you want a more mature option, that's where TypeScript comes in. It enables better management of component states, properties, events, and so on.

TS also implements many best coding practices and built-in type checking to approve the syntax and coding styles of your code.

For a new React.JS project, there are many ways to configure TypeScript. There are tools that allow you to run React and TypeScript online, which can be useful for debugging or making shareable reproductions. Examples of these tools include StackBlitz and CodeSandbox, or you can use this React TypeScript Cheatsheets checklist as a reference.

You can also simply use Create React App and set it up via your terminal with this command:

npx create-react-app my-app --template typescript

For an existing React project, create-react-app uses Babel to compile the JavaScript code. So for TypeScript you'll just need to install a few TypeScript-related packages like @types/react and @types/react-dom in your project.

Don't forget the various compilation options that you'll need to define in the tsconfig.json file. dom must be included in lib (Note: if no liboption is specified, dom is included by default) and JSX must be set to one of the valid options. Preserved should be sufficient for most applications.

All that's left is to rename the files to TypeScript and convert the code to TypeScript (component, and so on). JavaScript files in the React application can be renamed using the extension .tsx for files containing JSX (React) code and .ts for files containing standard TypeScript code.

For example, if you have a src/App.js file, you can rename it to src/App.tsx. Don't forget to do the same for the other files.

Now open the .tsx files you've renamed and start adding types to declarations, React components, and any other appropriate places.

npm install @types/react @types/react-dom

or if you miss certain dependencies you can run this:

cd mon-app
npm install typescript @types/node @types/react @types/react-dom @types/react-scripts --save

Now you're all set to use TS in your React projects.

How to Use TypeScript with Next.js:

TypeScript can help improve the performance of server-side rendering (SSR) and client-side rendering (CSR) applications by detecting errors early and facilitating type sharing between server and client.

It also enables better integration with Next.js, such as interfaces for SSR data and type annotations for routing functions.

Next.js provides a TypeScript-first development experience for building your React applications. It comes with built-in TypeScript support for automatically installing the necessary packages and configuring the proper settings.

For new projects just use create-next-app which now comes with TypeScript by default.

npx create-next-app@latest

In your existing projects, the first thing to do is install or add TypeScript to your project by renaming a file to .ts / .tsx. Run next dev and next build to automatically install the necessary dependencies and add a tsconfig.json file with the recommended config options.

If you already had a jsconfig.json file, copy the paths compiler option from the old jsconfig.json into the new tsconfig.json file, and delete the old jsconfig.json file.

Conclusion

TypeScript has been steadily growing in popularity in the web development ecosystem, thanks to its performance, type safety, and productivity advantages.

As the preferred choice for technologies such as ReactJS, Next.js, Angular and others, TypeScript improves code quality, facilitates collaboration between development teams, and enables the creation of high-performance, scalable web applications.

For more information on TypeScript, here are some helpful resources:

• TypeScript - Official documentation

• Microsoft Learn - TypeScript

• TypeScript course on freeCodeCamp

Thanks for reading. You can find me on LinkedIn here, and follow me on all socials @AdalbertPungu.

Sass is a CSS preprocessor that helps you manage tasks in large projects where the style sheets get larger, you have a number of lines of CSS code, and it becomes difficult to maintain your CSS codes.

This is where Sass becomes useful, as it has features that don't yet exist in CSS like nesting, creating functions with mixins, inheritance, and more. These features will help you write maintainable CSS code.

Sass lets you reuse your code, split it into files, and it also helps you create functions, variables, nest your CSS selectors, and other shortcuts.

How Sass Works

The web browser does not understand Sass code, though – it only understands CSS code. This means that you have to transform the Sass code into CSS code.

To do this, the compiler will generate a file with the CSS code. This transformation is called compilation. When you write Sass code in a .scss file, it is compiled into a regular CSS file that the browser will use to display it on the web page.

Why Use Sass?

There are many advantages to using Sass, so let's look at some of them now:

First, Sass is easy to understand if you know CSS. Since it's a CSS preprocessor its syntax is similar.

Also, if you use Sass, your CSS code will be compatible with all versions of browsers.

Sass also makes it possible to reuse your code by creating variables and functions with mixins (cutting up pieces of code) that can be reused over and over again. This helps you save time and allows you to code faster.

Speaking of saving time, Sass reduces the repetition of writing CSS code. This is thanks to its features like functions, variables, inheritance, and so on.

Finally, Sass is compiled to CSS and adds all the necessary vendor prefixes so you don't have to worry about writing them manually.

How to Install and Configure Sass

In this article, I'll show you two ways to install Sass.

How to Install Sass with Node.js

First, we'll download and install Node. Then we'll use the JavaScript package manager npm to install Sass and configure it in your project.

We are going to do a global installation, because this will save you from installing it every time you plan to work in your projects with Sass.

Here are the steps to follow to install and set up Sass in a project:

First, open your terminal and type:

npm install -g scss

Again, this is global installation. If you do this, you avoid installing it every time you plan to work with Sass in your projects.

Then, in the project folder, create a Sass file in the one you are going to work on:

style.scss

style is the file name and .scss is the Sass extension name.

Then you will use the following command to generate a style.css file from the SASS file:

sass --watch style.scss style.css

style.scss is the source file and style.css is the destination file where Sass generates the CSS code.

Now installation and configuration are complete! You can use Sass in your projects.

But before we get into how to use Sass, I want to show you a second way of doing it. I recommend this way, as it is the simplest and easiest way to install and configure Sass.

How to Install Sass Using VS Code

First, download and install Microsoft's VS Code editor if you haven't already. Then launch the editor so you can download the Live Sass Compiler extension.

And that's all you have to do. Once the installation is done, you'll be able to use Sass in your projects. Easy, right?

How to Use Sass in a Project

To understand how to use Sass, we will work on an example project where we will create two grids. The idea here is not to learn everything about Sass but what you see is mostly what you need to know to start using Sass.

Here is an overview of what we will create to understand Sass.

You might be wondering why I took the grid example? Well, because we often use grids in web pages and they're simple to understand.

First of all, you should know that we'll do all the coding in the Sass file (style.scss) and not in the style.css file. It is Sass that will generate a CSS file for us with the same code.

To start, create a folder with two folders inside, CSS and images. Then inside the CSS folder create a file with the Sass extension – in my case it's style.scss.

Then open it and the file will be detected right away. Below the editor a button will appear named Watch Sass. Just click on it to tell Sass to watch this file and start generating (compiling) code in the CSS file.

Once SASS finishes compiling it will create three files in the project's CSS folder: style.css, style.scss, and style.css.map. It tracks all the changes and it is ready to generate CSS code.

If you come back soon to continue working, all you have to do is open the file which has the extension .scss. Then click on Watch Sass for Sass to start generating the modifications in the CSS file (otherwise nothing will be generated in the CSS file).

I hope it's going ok so far. You have just seen how to install, configure, and start using Sass in your project. So now let's continue with our example of the grids to understand the different functionalities Sass brings.

How to Use Variables in Sass

Before seeing how to create Sass variables, create an index.html file copy and paste the code below in the file:

<!DOCTYPE html>
<html lang="en">
      <head>
            <meta charset="UTF-8">
            <meta http-equiv="X-UA-Compatible" content="IE=edge">
            <meta name="viewport" content="width=device-width, initial-scale=1.0">
            <title>card with sass</title>
      </head>
      <body>

            <div class="card">
                  <img src="https://images.unsplash.com/photo-1524749292158-7540c2494485?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxzZWFyY2h8MTd8fGRldmVsb3BlcnN8ZW58MHx8MHx8&auto=format&fit=crop&w=500&q=60" alt="">
                  <div class="card_content">
                        <h2 class="card_title">Lorem</h2>
                        <p class="card_description">Lorem, ipsum dolor sit amet consectetur adipisicing elit. Rerum porro dolores sapiente.</p>
                  </div>
            </div>

            <div class="card card_dark">
                  <img src="https://media.istockphoto.com/photos/put-more-in-get-more-out-picture-id1291318636?b=1&k=20&m=1291318636&s=170667a&w=0&h=UvVIk7wwkN3X9OFm8gBlWWviV5vAjfrq2ejYP30JmnA=" alt="">
                  <div class="card_content">
                        <h2 class="card_title">Lorem</h2>
                        <p class="card_description">Lorem ipsum dolor sit amet, consectetur adipisicing elit. Atque amet obcaecati nihil.</p>
                  </div>
            </div>

      </body>
</html>

Run the file in your browser to see the result.

Sass lets you create variables, but I want to show you a difference between Sass and CSS.

body {
    font-family: 'Poppins', Helvertica, sans-serif;
    background-color: #ab99ca;
    padding: 2rem;
    min-height: 100vh;
    display: flex;
    align-items: center;
    justify-content: center;
}

If you look at this example, it's CSS. But if in the project I want to reuse any color, padding, or font, I have to rewrite the same code (in CSS).

But with Sass I can create variables so I can reuse these features. To create a variable in Sass, we use the dollar sign $ followed by the variable name and a colon for the value. Keep in mind that it's best to create a name that reflects the object you're going to use.

/* Creating and Using Variables */

$fonts: 'Poppins', Helvertica, sans-serif;
$primary-color: #ab99ca;
$spacing: 2rem;

body {
    font-family: $fonts;
    background-color: $primary-color;
    padding: $spacing;
    min-height: 100vh;
    display: flex;
    align-items: center;
    justify-content: center;
}

Add the above code in the style.scss file. Since we are working with a Sass file and HTML does not recognize Sass, to see the results we'll specify the CSS file that has been generated in our file index.html.

How to Link the CSS File

It's really important to link the CSS file to index.html, to allow the CSS file to apply the CSS styles to the HTML. Otherwise there will be no styling applied and you will only see the code produced by the HTML.

So we will link our CSS file in the index.html file. In my case:

<link rel="stylesheet" href="css/style.css">

Run the file in your browser to see the result.

We will now see how to organize the code thanks to IMPORTS. The code will be cut into files while we keep using our example.

When creating a file, the file name will be followed by an underscore(_) at the beginning to prevent it from being compiled by Sass.

Create three files:

• _variables.scss: to add the variables

• _mixins.scss: to add the functions that we will reuse

• _card.scss: to add the styles of our cards

Copy and paste the variables you created in the style.scss file and put them in the _variables.scss file:

    $fonts: 'Poppins', Helvetica, sans-serif;
    $primary-color: #ab99ca;
    $spacing: 2rem;
    $dark-grey: #999;

For the _mixins.scss file, this is where we'll create the reusable functions with mixins.

Mixins allow you to create reusable functions. To declare a function you must enter @mixin name_fonction { content } or if your function has a parameter, you must enter @mixin name_fonction($name_variable) { content }.

To use mixins, you have to import it by typing @include namefunction(); which saves time in a large project.

Add this code to the _mixins.scss file:

@mixin flex-center {
    display: flex;
    align-items: center;
    justify-content: center;
}

/* $radius is the parameter of the function */

@mixin border-radius($radius) {
    -webkit-border-radius: $radius;
    -moz-border-radius: $radius;
    border-radius: $radius;
}

For the _card.scss file, add this code to it:

.card {
    background-color: white;
    width: 20rem;
    overflow: hidden;
    margin: 2rem;
    box-shadow: 5px 5px 5px 5px #000;
    @include border-radius(0.5rem); /* using the mixins function */

    img {
        height: 15rem;
        background-size: cover;
        background-position: center center;
    }

    .card_content {
        padding: $spacing;
    }

    .card_title {
        margin: 0;
        color: black;
    }

    .card_description {
        margin: 0;
        color: $dark-grey;
    }

    &_dark {

        background-color: black;

        .card_title {
            color: white;
        }
    }

}

In the code above we're using nesting and aliases. Nesting helps us simplify the way we write our CSS styles and allows us to nest CSS selectors.

For aliases you can use (&) or (and) followed by the class name that will resume the parent selector's code.

To use an alias, you must import it by typing the alias followed by the name of the variable (&_dark).

If you try to run the index.html file, nothing will change. It does not change because we have created files that are not related to index.html and our style.sass file only generates the code it has.

To fix this, we'll import all the files we've created into the style.sass file so that when SASS does the monitoring, it'll generate the code of those files.

/* file import */
@import 'variables';
@import 'mixins';
@import 'card';

For the style.scss file, add the above code. The style.scss file should be like this:

/* file import */

@import 'variables';
@import 'mixins';
@import 'card';

body {
    font-family: $fonts; /* variable usage */
    background-color: $primary-color;
    padding: $spacing;
    min-height: 100vh;
    @include flex-center(); /* using the mixins function */
}

In the previous code, I imported the files (SASS import) into style.css so that they can be tracked and generate code when there are changes.

Run the index.html file in your browser to see the result.

If you get the same result as in the capture above, congratulations, you now understand how Sass works.

Here is the preview link for the project we built: https://adalbertpungu.github.io/card_with_sass/

And here's the GitHub repository link:

Conclusion

In this article, you learned how Sass works by building a simple photo grid. In this small project, we've covered many core Sass features, but not all of them. So I hope you will start using it in your projects to learn more.

You can check the documentation if you want to dive deeper: https://sass-lang.com/documentation.

That’s all for this article. Thank you for reading! I think you’re ready to try using Sass.

Happy coding.

Follow me on Twitter: twitter.com/AdalbertPungu