@umbraco/headless-client/README.md

Node.js client library for the Umbraco Headless APIs

<p align="center">
  <img src="https://github.com/umbraco/Umbraco.Headless.Client.NodeJs/raw/master/.github/img/logo.png" alt="Umbraco Heartcore Logo" />
</p>

<hr>

# NodeJS Client Library for Umbraco Heartcore

Umbraco Heartcore is the headless CMS version of Umbraco as a Service.

This repository contains the Node.JS client library for the Umbraco Heartcore REST APIs.

## Prerequisites

* [NodeJS](https://nodejs.org) 10 or newer

## Install

```bash
> npm install @umbraco/headless-client
```

## Usage

Create a client, then call commands on it

```typescript

// client.ts
import {Client} from '@umbraco/headless-client'

const client = new Client({
  projectAlias: 'your-project-alias',
  apiKey: 'your-api-key',
  language: 'iso-code', // can be overwritten per method
  preview: true // true/false if the preview API should be used
})

export default client

// rootLinks.ts
async function rootLinks(client: Client) {
  const rootContent = await client.delivery.content.root()

  const childPages = rootContent.map(child => ({
    url: child._url,
    name: child.name
  }))

  return childPages
}

function linkGenerator(links: {url: string, name: string}[]) {
  return links.map(link => {
    return `<a href="${link.url}">${link.name}</a>`
  })
}

async function main() {
  const rootLinks = await rootLinks(require('./client').default)
  const links = linkGenerator(rootLinks)
  console.log(links)
}

```

## Documentation

General documentation for Umbraco Heartcore can be found on [our.umbraco.com](https://our.umbraco.com/documentation/Umbraco-Heartcore/).

API documentation for the Client library can be generated by running the following

```bash
> npm install # install dependencies
> npm run build # build the source
> npm run docs # generate the documentation
```

This will generate markdown files in `docs/api` that can be openend in any markdown viewer.

A simple way to view them is to use [markserv](https://www.npmjs.com/package/markserv) by running

```bash
> npx markserv docs/api
```