NestJS

The below instructions will guide you through setting up your NestJS application and deploying it in two steps. Follow along to get your project up and running.

Installation guide

1

Install using your favourite package manager

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

2

Add import into your main.ts file

Include registerAppear() directly in to your main.ts file. See example.

Ensure this script is included prior the bootstrap function.

main.ts

import { registerAppear } from "@appear.sh/introspector/node"

registerAppear({
  apiKey: process.env.APPEAR_REPORTING_KEY,
  environment: process.env.NODE_ENV,
  serviceName: "User Service", // name of the service you're instrumenting        (optional)
})

3

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.

---

Example installation

import { NestFactory } from "@nestjs/core"
import { AppModule } from "./app.module"
import { registerAppear } from "@appear.sh/introspector/node"

registerAppear({
  apiKey: "test-key",
  environment: "test",
  reporting: { endpoint: process.env.COLLECTOR_URL },
})

async function bootstrap() {
  const app = await NestFactory.create(AppModule)
  const server = await app.listen(0)
  const port = server.address().port
  console.log(`Server started on port ${port}`)
}
bootstrap()

---

Configuration

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

config.ts

export interface AppearConfig {
  /**
   * API key used for reporting
   * you can obtain your reporting key in keys section in Appear settings
   * reporting keys have only the permission to report schema and can't read any data
   * you can use any method to inject the key, in examples we used env variable
   */
  apiKey: string
  /**
   * Environment where the report is sent from
   * it can be any string that identifies environment data are reported from.
   * Often used as "production" or "staging", however if you're using some form of ephemeral environment feel free to use its identifier
   */
  environment: string

  /**
   * Name of current service
   * used to improve accuracy of matching, useful when you're not using descriptive host names in incoming requests
   * for example if you're using directly IP addresses
   *
   * @optional
   * @default hostname if not provided the service name will be detected from hostname
   */
  serviceName?: string

  /**
   * A flag you can use to disable introspector completely
   * useful if you don't want to report in certain environments
   *
   * @default true
   */
  enabled?: boolean

  /**
   * Enable debug mode which will output detailed debug information to the console,
   * including all reported traffic, validation errors, and other diagnostic data.
   * Useful for troubleshooting and understanding what data is being sent to Appear.
   *
   * @default false
   */
  debug?: boolean

  /** configuration of how often and where data are reported */
  reporting?: {
    /**
     * endpoint reports are sent to, useful if you want to audit what data are reported
     * simple audit can be done by navigating to https://public.requestbin.com/r which will give you endpoint url you can paste here and see in the debugger all traffic
     *
     * @default https://api.appear.sh/v1/reports
     */
    endpoint?: string
  }

  interception?: {
    /**
     * Optional function that allows to filter what request/response pair is getting analyzed and reported.
     * You can reuse default filter by importing it from `import { defaultInterceptFilter } from "@appear.sh/introspector" and using it inside the function`
     *
     * @default (req, req, config) => req.destination === "" && !request.url.includes(config.reporting.endpoint)
     */
    filter?: (
      request: Request,
      response: Response,
      config: ResolvedAppearConfig,
    ) => boolean
  }
}

---

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