Getting started

Before you start

You need to pick the base library you want to create your project with.

If your project consists of few simple functions and you’re comfortable dealing with raw http requests, you can start with @httpc/server. Otherwise, it’s strongly suggested to build upon @httpc/kit as it offers lots of features you’ll end up using anyway.

Installation

Requirements

• node v16.13+
• npm or equivalent package manager

Start from a template

You can quickly setup a project from a template.

npm create httpc

pnpm create httpc

yarn create httpc

Manual setup

If you already have a package, you can manually add httpc to your project.

# for server-based projects
npm install @httpc/server
# for kit-based projects
npm install @httpc/kit tsyringe reflect-metadata

# used in both, for development tasks
npm install @httpc/cli --save-dev

# for server-based projects
pnpm add @httpc/server
# for kit-based projects
pnpm add @httpc/kit tsyringe reflect-metadata

# used in both, for development tasks
pnpm add @httpc/cli --save-dev

# for server-based projects
yarn add @httpc/server
# for kit-based projects
yarn add @httpc/kit tsyringe reflect-metadata

# used in both, for development tasks
yarn add @httpc/cli --dev

Start the server

If you used a template, you can start the development server. Enter the project directory and run:

npm run dev

pnpm dev

yarn run dev

Generate the client

After you wrote some functions, you can generate the client package. In a project directory, just run:

npm run generate:client

pnpm generate:client

yarn run generate:client

Underneath it runs the @httpc/cli with httpc client generate. You can checkout more about client generation with all the advanced options.

Project structure

The minimal project is composed by:

project/
├─ src/
│  ├─ calls/
│  │  └─ index.ts
│  └─ index.ts
├─ httpc.json
├─ package.json
└─ tsconfig.json

import { createHttpCServer } from "@httpc/server";
import calls from "./calls";


const server = createHttpCServer({
  calls,
  cors: true
});

server.listen();

function echo(message: string) {
    return message;
}

function greet(name: string) {
    return `Hello ${name}`;
}


export default {
    echo,
    greet,
}

{
  "name": "@service/api-client",
  "entry": "./src/calls/index.ts",
  "dest": "./client",
}

The core files:

• src/index.ts

  The entry point of your application, where you setup the httpc server. Here you can specify parsers, global middlewares and in general application-wide settings.

• src/calls/index.ts

  The functions you want to expose. You can organize and group your calls in multiple files. Call files are easily composed and nested as they are standard javascript objects.

• httpc.json

  The configuration used to generate the client of your API. In addition to the httpc.json file, you can specify the configuration in other ways.

Next steps

• Read the Tutorial
• Checkout the client generation