Appear docs
HomepageGitHubAPI toolkitSign inGet demo
  • Getting Started
    • Welcome to Appear
    • How Appear works
    • Who is Appear for?
    • Get In Touch
    • Installation
  • Installation
    • Javascript / Typescript
    • Framework specific installations
      • NestJS
      • NextJS
      • Custom integrations
  • Explanations
    • Branches and environments
  • Connections
  • Managing your APIs
    • Creating a service
    • Add service via URL
    • Grouping & filtering
    • Editing your APIs
    • Overriding/updating a service
  • OpenAPI spec version
  • Tagging services
  • Service Resources
    • Resource map
  • Managing your organisation
    • Managing team members
    • Adding verified domains
  • Resources
    • FAQs
    • Product Map
    • Open-source
Powered by GitBook
On this page
  • Installation steps
  • Configuration

Was this helpful?

  1. Installation

Javascript / Typescript

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

PreviousInstallationNextFramework specific installations

Last updated 1 month ago

Was this helpful?

This JS introspector is a tool that listens to both incoming and outgoing traffic in JS runtime (browser, node) and detects the shape (schema) of it and reports this schema to Appear platform where it's further merged, processed, and analysed

Because it reports only the schema of the traffic, it never sends any actual content of the data nor PII.

The following installation guide covers Node server along with thin servers like Express, Fastify, Koa, etc.

Installation steps

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

Create a new JS file

You can place the new appear.js file anywhere in your file structure.

The specific method of how to do this may vary on your chosen framework.

appear.js
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

Add Node hook

Add the hook into Node by adding the --import parameter to the start script. This is usually in package.json .

node --import ./appear.js server.js

If your framework use some CLI wrapper around node you can also use env variable approach.

NODE_OPTIONS='--import ./appear.js' node-wrapper start
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 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
   * 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

  /** 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
     *
     * @default (req, req, config) => req.destination === "" && request.url !== config.reporting.endpoint
     */
    filter?: (
      request: Request,
      response: Response,
      config: ResolvedAppearConfig,
    ) => boolean
  }
}

We're actively working on improving how Appear works with NextJS. If you have any queries or require support with the above instructions, please .

contact us
Appear