Skip to main content

​
Installing the SDK

The SDK is distributed as an npm package and can be installed using your preferred package manager. 
npm install @obsidian-ai-providers/sdk

​
Adding to package.json

The SDK will automatically be added to your package.json dependencies:
package.json
{
  "dependencies": {
    "@obsidian-ai-providers/sdk": "^1.5.0",
    "obsidian": "latest"
  }
}

​
Importing SDK Styles

The SDK includes a fallback settings tab UI that requires styles to be imported. Add the following import to your plugin’s main stylesheet:
styles.css
@import '@obsidian-ai-providers/sdk/styles.css';
The SDK styles are required for the fallback settings tab that appears when the AI Providers plugin is not yet loaded or activated.

​
esbuild Configuration

You must configure your esbuild setup to load CSS files. Update your esbuild.config.mjs file:
esbuild.config.mjs
export default {
  entryPoints: ['main.ts'],
  bundle: true,
  external: [
    'obsidian',
    'electron',
    '@codemirror/*'
  ],
  format: 'cjs',
  target: 'es2018',
  logLevel: 'info',
  sourcemap: 'inline',
  treeShaking: true,
  outfile: 'main.js',
  loader: {
    '.ts': 'ts',
    '.css': 'css'  // Add CSS loader
  },
}
Without the .css loader in your esbuild config, the SDK styles will not be bundled correctly and the fallback UI will not display properly.

​
Alternative: Copy Styles Manually

If you prefer not to configure the CSS loader, you can manually copy the contents of @obsidian-ai-providers/sdk/styles.css into your own stylesheet. 
# View the SDK styles
cat node_modules/@obsidian-ai-providers/sdk/styles.css
Then paste the contents into your plugin’s styles.css file.

​
Version Compatibility

The SDK uses semantic versioning and maintains compatibility requirements with the AI Providers plugin:
1

SDK Version 1.5.0+

Requires AI Providers plugin Service API v3 or higher. This version introduces:
  • execute() returns Promise<string> with inline streaming via onProgress
  • Cancellation support via AbortController
  • Deprecated chainable IChunkHandler (legacy compatibility only)
2

Compatibility Check

The SDK automatically checks version compatibility when initializing. If the installed AI Providers plugin is incompatible, a fallback settings tab will be shown.
3

Migration Guides

If upgrading from older SDK versions, refer to the migration guides:
The SDK is designed to work with Obsidian’s plugin API. Ensure your plugin’s manifest.json specifies a minimum Obsidian version that supports the features you’re using.

​
Next Steps

After installation, proceed to Integration to learn how to initialize the SDK in your plugin.

Build docs developers (and LLMs) love

Get started for freeTalk to us