# NestJS

## Installation guide

{% stepper %}
{% step %}

### Install using your favourite package manager

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

{% endstep %}

{% step %}

### Add import into your main.ts file

Include registerAppear() directly in to your main.ts file. See [example](#example-installation). 

{% hint style="warning" %}
Ensure this script is included prior the bootstrap function.
{% endhint %}

{% code title="main.ts" overflow="wrap" %}

```typescript
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)
})
```

{% endcode %}
{% endstep %}

{% step %}

### 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](https://docs.appear.sh/installation/sdk-installations/broken-reference) with your credentials to view the services that appear. You may need to refresh the page periodically.
{% endstep %}
{% endstepper %}

***

## Example installation

```typescript
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.

{% code title="config.ts" overflow="wrap" fullWidth="false" %}

```javascript
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
  }
}
```

{% endcode %}

***

If you have any queries or require support with the above instructions, please [contact us](https://docs.appear.sh/getting-started/get-in-touch).