Ship SDK

A universal SDK for ShipStatic. Works in Node.js and the browser. NPM / GIT

npm install @shipstatic/ship

Quick Start

import Ship from '@shipstatic/ship';

const ship = new Ship({ apiKey: 'ship-...' });
const deployment = await ship.deploy('./dist');

Authentication

Requires an API Key or deploy token.

// API key - persistent, full access
new Ship({ apiKey: 'ship-...' });

// Deploy token - single-use
new Ship({ deployToken: 'token-...' });

// Set after construction
ship.setApiKey('ship-...');
ship.setDeployToken('token-...');

Precedence: Deploy token → API key → Cookie (browser only).

Deploy Options

await ship.deploy('./dist', {
  labels: ['production'],
  onProgress: ({ percent }) => console.log(`${percent}%`),
  signal: AbortSignal.timeout(30000),
  spaDetect: false,
  pathDetect: false,
  subdomain: 'my-site',
});

Resources

Deployments

ship.deployments.upload(path, options?)
ship.deployments.list()
ship.deployments.get(id)
ship.deployments.set(id, { labels })
ship.deployments.remove(id)

Domains

ship.domains.set(name, { deployment?, labels? })
ship.domains.list()
ship.domains.get(name)
ship.domains.remove(name)
ship.domains.validate(name)
ship.domains.verify(name)
ship.domains.dns(name)
ship.domains.records(name)
ship.domains.share(name)

domains.set() is a single upsert operation. Omitted fields are preserved on update:

ship.domains.set('staging');                              // Reserve
ship.domains.set('staging', { deployment: 'abc123' });    // Link
ship.domains.set('staging', { deployment: 'xyz789' });    // Switch
ship.domains.set('staging', { labels: ['prod'] });        // Label only

Once linked, a domain cannot be unlinked - switch to a different deployment or delete the domain.

Tokens

ship.tokens.create({ ttl?, labels? })
ship.tokens.list()
ship.tokens.remove(token)

Account

ship.account.get()     // or ship.whoami()
ship.ping()            // returns boolean
ship.getConfig()       // platform config and plan limits

Browser

import Ship from '@shipstatic/ship';

const ship = new Ship({ apiKey: 'ship-...' });

// From file input
await ship.deploy(fileInput.files);

// From blobs
await ship.deploy([
  { path: 'index.html', content: new Blob(['<html>...</html>']) }
]);

Events

ship.on('request', (url, init) => {});
ship.on('response', (response, url) => {});
ship.on('error', (error, url) => {});

Error Handling

import { isShipError } from '@shipstatic/types';

try {
  await ship.deploy('./dist');
} catch (error) {
  if (isShipError(error)) {
    error.isAuthError();
    error.isValidationError();
    error.isNetworkError();
    error.isFileError();
    error.isConfigError();
  }
}

TypeScript

Full type safety with exported types:

import type { ShipClientOptions, DeploymentOptions, ShipEvents } from '@shipstatic/ship';
import type { Deployment, Domain, Account, StaticFile } from '@shipstatic/types';

Configuration

Resolved in order of precedence:

Constructor options
Environment variables (SHIP_API_KEY, SHIP_API_URL)
.shiprc file
package.json "ship" key