Node.js SDK: Installation & Setup

The Stringhive Node.js SDK gives you a CLI and a TypeScript client for pushing and pulling translations from your JavaScript or TypeScript projects.

Requirements

Node.js 22 or higher

Install

npm install stringhive

Or install globally to use the CLI from anywhere without npx:

npm install -g stringhive

Or with yarn or pnpm:

yarn add stringhive
pnpm add stringhive

Configure

Set your API token in .env:

STRINGHIVE_TOKEN=shv_yourtokenhere

STRINGHIVE_URL defaults to https://www.stringhive.com/api. Only set it if you're running a self-hosted server.

Config file

Drop a stringhive.config.ts (or .js) at your project root for options you'd rather not repeat on every command:

import { defineConfig } from 'stringhive'

export default defineConfig({
  hive: 'my-app',
  langPath: './src/locales',
  sourceLocale: 'en',
  format: 'json',
  exclude: [
    // 'en.json',    // skip a specific file
    // '*.json',     // skip all JSON files
  ],
  include: [
    // 'fr.json',    // only process this file
  ],
  push: {
    conflictStrategy: 'keep',
  },
  pull: {
    includeSource: false,
  },
})

CLI flags always win over the config file. The config file always wins over built-in defaults.

Config options

Option	Description
`hive`	Default Hive slug — lets you run `stringhive push` without specifying it every time
`langPath`	Path to your translations directory (default: `./lang`)
`sourceLocale`	Source locale code (default: `en`)
`format`	File format: `json` (default)
`exclude`	Glob patterns of files to skip on every command
`include`	Glob patterns of files to exclusively include
`push.conflictStrategy`	Default conflict strategy for push: `keep` or `clear`
`pull.includeSource`	Whether pull should also include the source locale

Verify the connection

npx stringhive push --dry-run

If it lists what would be pushed, you're connected. If you get an auth error, double-check your token.

TypeScript support

The SDK ships with full TypeScript types. No @types package needed. The defineConfig helper gives you autocomplete for all config options.