Installation & Setup

Prerequisites

Before you start building, make sure you have:

• Node.js 18+ and a package manager (npm, yarn, or pnpm)
• A Vim Connect developer account — contact your Vim representative to get one
• A registered application — your app must be registered on the Vim Connect platform with an OAuth client ID and secret
• The Vim Connect Chrome extension — install it from the Chrome Web Store (search "Vim Connect") or request access from your Vim representative
• Access to a supported EHR — the extension must be running on an EHR page for the SDK to connect

Installation

npm install @vimconnect/app-sdk

The SDK requires zod as a peer dependency for runtime validation schemas:

npm install zod

Two shortcuts worth taking first

• Don't want to start from an empty project? Fork the Demo App — a working Vim app with the OAuth flow and an explorer that drives every capability your manifest declares.
• Building with an AI coding agent? Install the vim-app-sdk-docs skill — it ships inside @vimconnect/app-sdk and makes your agent look up real entity fields, event ids, and method signatures instead of guessing them.

How It Works

The @vimconnect/app-sdk package provides:

1. initVimSDK() — Loads the core SDK from the Vim CDN and initializes a connection with the Chrome extension
2. Typed wrappers — Full TypeScript types for entities, events, context keys, and API methods
3. Zod schemas — Runtime validation schemas for all entity types (Patient, Encounter, Order, Referral)

Your application runs inside the Vim Hub sidebar, which is injected into the EHR by the Vim Connect Chrome extension. The SDK communicates with the extension via a MessageChannel to receive events, read data, and perform writeback operations.

Browser Tab (EHR)
├── Vim Connect Extension (content script)
│   ├── Detects the EHR system
│   ├── Extracts data using configured rules
│   └── Injects the Vim Hub (sidebar / overlay)
│       ├── App Hub (shows installed apps)
│       └── Your App (iframe)
│           └── @vimconnect/app-sdk
│               └── MessageChannel → Extension

The core SDK library is loaded at runtime from a CDN — it is not bundled into your application. This means:

• Your bundle stays small
• The core SDK can be updated independently
• All apps on the platform share the same communication layer

Project Structure

A typical Vim app project looks like this:

my-vim-app/
├── src/
│   ├── app/
│   │   ├── launch/page.tsx      # OAuth launch redirect
│   │   ├── app/page.tsx         # Main app (SDK initialized here)
│   │   └── api/auth/token/
│   │       └── route.ts         # Server-side token exchange
│   ├── lib/
│   │   └── sdk-config.ts        # Environment-based config
│   └── components/              # Your UI components
├── .env.local                   # CLIENT_SECRET (server-only)
├── .env                         # NEXT_PUBLIC_* vars
├── package.json
└── next.config.js

Environment Variables

Next Steps

• Quick Start — Build a minimal app step by step
• Initialization — SDK initialization options and methods
• Authentication — Full OAuth 2.0 implementation guide