Publisher’s guide

This guide is intended for library others who want to publish their API reference on apiref.page.

apiref.page generates an API reference site from API Extractor’s “doc model” file.
- See the Generate a doc model file section.
The doc model file should be published in your package to the npm registry.
- See the Publishing the API reference section.

Generate a doc model file

Use the API Extractor tool to generate a doc model file.
- API Extractor works by processing .d.ts files.
  - For TypeScript libraries, just set declaration to true in your tsconfig.json file.
  - For JavaScript libraries, you can write a .d.ts file by hand (easier) or use tsc --allowJs --declaration --emitDeclarationOnly to generate .d.ts file from your JavaScript source.
- Your library’s API surface must be “documentable” by API Extractor and API Documenter.
  - apiref.page is based on API Extractor and API Documenter’s documentation model, which only encompasses a limited subset of TypeScript constructs.
  - Any construct that cannot be modeled by API Extractor or API Documenter will not work with apiref.page either.
  - It is not a goal to suppport all kinds of possible constructs. Rather, we prefer standard coding stereotypes over flexible free-form expressions.
If done correctly, you will get an .api.json file.

Using apiref in an existing project may require changing your API, so that it uses only the constructs supported by API Extractor and API Documenter. It may result in breaking changes.

Previewing the documentation locally

To iterate more quickly, you can preview the API reference locally.

Make sure you have your .api.json file ready.

Install or upgrade the apiref CLI: npm install --global apiref
Run apiref -i <path/to/your>.api.json to start a local preview server.
Go to http://localhost:3000/
When you make change to the .api.json file, just hit Refresh to see the changes.

The apiref npm package is updated quite often (whenever a new version of the website is deployed). Install the latest version to make sure that the local preview looks consistent with the live website.

Publishing the API reference

Add a docModel field to your package.json file, pointing to the .api.json file.
Make sure the package includes the .api.json file along with the other built files.
Publish your package to npm.

Viewing the API reference on apiref.page

Once published, you can access the API reference of your package at these URLs:

https://apiref.page/package/{package-name}
https://apiref.page/package/{package-name}@{version}