SDK

The Raster SDK connects your app to a user's Raster libraries. It comes as two MIT-licensed npm packages:

• @raster-app/react: the drop-in RasterPicker, plus React bindings. It includes everything in the core.
• @raster-app/sdk: the framework-free core, with the client, sign-in, image URL helpers, and formatters.

Install

For a React app (React 18 or 19):

npm install @raster-app/react

For any other app:

npm install @raster-app/sdk

Both packages are ESM-only and run in the browser or Node.js 22.12+.

Quick start

RasterPicker is a complete asset picker. Render it inside a RasterProvider and import its stylesheet:

import {
  RasterPicker,
  RasterProvider,
  getFullSizeUrl,
  localStorageCredentialStore,
} from '@raster-app/react'
import '@raster-app/react/styles.css'

export function Picker({ onImage }: { onImage: (url: string) => void }) {
  return (
    <RasterProvider
      config={{
        host: { name: 'My App', openExternal: (url) => window.open(url, '_blank') },
        credentials: localStorageCredentialStore(),
      }}
    >
      <RasterPicker onPick={(asset) => onImage(getFullSizeUrl(asset) ?? '')} />
    </RasterProvider>
  )
}

• host.name is the app name Raster shows on its sign-in page. host.openExternal opens that page (see The host).
• localStorageCredentialStore() keeps the user signed in across reloads (see Where the credential is stored).

The picker fills its container, so give the container a height. With React Server Components, render it from a Client Component ('use client').

In the picker, the user can:

• Sign in with a code they approve in Raster, or connect an organization API key when organizationId is unset.
• Choose an organization and library, or search the whole organization.
• Open an asset to see it large with its variants, open it in Raster, or pick it when you pass onPick.
• Upload files to libraries they can write to, upload variants, and set a variant as the default.

onPick receives the Asset and its organization's id. getFullSizeUrl(asset) returns its full-size URL.

Props

Next steps

• Authentication: device sign-in, API keys, and credential storage.
• React: RasterPicker, RasterProvider, and hooks for your own UI.
• Client: createRasterClient, its methods, and helpers.
• Errors: RasterApiError and its codes.