Javascript / Typescript

Using our Javascript & Typescript introspector is simple: two steps and Appear gets to work.

1

Install the Appear package (select one)

npm i @appear.sh/introspector // or
yarn add @appear.sh/introspector // or
pnpm add @appear.sh/introspector

2

Drop in the snippet in the entry point of your service

import * as Appear from '@appear.sh/introspector'

Appear.init({
  apiKey: 'your-api-key',
  environment: process.env.NODE_ENV,
})

3

If your service hosts an HTTP server (Express, NestJS, etc), you will need to hook Appear before your app starts

To do this, we expose a @appear.sh/introspector/hook package that does this for you. The easiest way to use this is to modify your node executable parameters.

For example:

• Before: node build/server.js

• After: node -r @appear.sh/introspector/hook build/server.js

Alternatively, if you have an entrypoint file that is run before requiring/importing your HTTP server dependency packages, calling Appear.init will work fine.

4

Log into Appear to view entries

The introspector will begin reporting the structure of your API services when they're interacted with. Log into Appear with your credentials to view the services that appear. You may need to refresh the page periodically.

Configuration

To configure how the introspector reports your schemas to Appear, you can adjust in the file below.

export interface AppearConfig {
  /** API key used for reporting */
  apiKey: string
  /** environment where the report is sent from */
  environment: string
  /**
   * flag you can use to disable introspector completely
   * useful if you don't want to report in specific environments
   *
   * @default true
   */
  enabled?: boolean

  /** configuration of how often and where data are reported */
  reporting?: {
    /**
     * endpoint reports are sent to, applicable if you want to audit what data is reported
     * A simple audit can be done by navigating to https://public.requestbin.com/r, which will give you the endpoint URL you can paste here and see in the debugger all traffic
     *
     * @default https://api.appear.sh/v1/reports
     */
    endpoint?: string
    /**
     * interval, how often are batches sent
     * `0` means that reports are sent immediately
     *
     * @default 5
     */
    batchIntervalSeconds?: number
    /** number of items in a batch before it reports them
     * report can be triggered by either time or size, depending on what happens first
     *
     * every schema is reported only once
     *
     * `0` means batching is disabled and reports are sent immediately
     *
     * @default 10
     */
    batchSize?: number
  }

  interception?: {
    /**
     * disables XHR introspection hook which may introduce noise in some situations
     *
     * @default false
     */
    disableXHR?: boolean
    /**
     * Optional function that allows filtering what request/response pair is getting analyzed and reported
     *
     * @default (req, req, config) => req.destination === "" && request.url !== config.reporting.endpoint
     */
    filter?: (
      request: Request,
      response: Response,
      config: ResolvedAppearConfig,
    ) => boolean
  }
}

If you have any queries or require support with the above instructions, please get in touch with us.