smslib

---

Open-source monorepo for sending SMS via multiple gateways/providers with a MailHog-style local dev server.

Features

• Multiple Providers - Twilio, MiMSMS, AlphaNet support out of the box
• TypeScript - Full type safety with strict mode
• Transport Pattern - Easily swap between production and mock servers
• Local Dev Server - MailHog-style UI for testing without hitting real APIs
• Docker Ready - Pre-built image available on GitHub Container Registry

Quick Start

# Install dependencies
pnpm install

# Start dev server (API + Web UI)
pnpm dev

# Or run individually
pnpm dev:api  # API on http://localhost:3000
pnpm dev:web   # Web UI on http://localhost:5173

Packages

Published to npm

Package	Version	Description
@smslib/types		Shared TypeScript interfaces
@smslib/core		SmsClient, FetchTransport
@smslib/adapter-twilio		Twilio SMS adapter
@smslib/adapter-mimsms		MiMSMS SMS adapter
@smslib/adapter-alphanet		AlphaNet SMS adapter

Apps

App	Description
dev-server/api	Express mock server (port 3000)
dev-server/web	Vite + React UI (port 5173)

Commands

pnpm build        # Build all packages
pnpm test         # Run unit tests
pnpm lint         # Lint all packages
pnpm typecheck    # TypeScript type checking

CI/CD

GitHub Actions

• CI Workflow (.github/workflows/ci.yml):

  • Lint and typecheck
  • Unit tests with Vitest
  • E2E tests with Playwright
  • Build verification

• Release Workflow (.github/workflows/release.yml):

  • Publishes packages to npm via Changesets
  • Builds and pushes Docker image to GCR

Changesets

This repo uses Changesets for version management and npm publishing.

To release a new version:

# Create a changeset (describe what changed)
pnpm changeset

# After merging to main, the release workflow will:
# - Version bump packages
# - Publish to npm
# - Push Docker image to GCR

Docker

Run the dev server using Docker:

# Pull and run the latest image
docker run -p 3000:3000 ghcr.io/mrmeaow/smslib-server:latest

# The web UI will be available at http://localhost:3000

Or use Docker Compose:

services:
  smslib:
    image: ghcr.io/mrmeaow/smslib-server:latest
    ports:
      - "3000:3000"

Build locally:

docker build -t ghcr.io/mrmeaow/smslib-server:latest apps/dev-server/docker
docker run -p 3000:3000 ghcr.io/mrmeaow/smslib-server:latest

Architecture

smslib/
├── packages/
│   ├── types/                    # Shared interfaces
│   ├── core/                     # SmsClient, Transport
│   └── adapters/                 # Provider adapters
│       ├── twilio/
│       ├── mimsms/
│       └── alphanet/
├── apps/
│   └── dev-server/
│       ├── api/                  # Express mock API
│       ├── web/                  # React UI
│       └── docker/               # Dockerfile
└── .github/workflows/           # CI/CD

Development

Adding a New Adapter

1. Create packages/adapters/<name>/
2. Implement SmsAdapter interface from @smslib/types
3. Add mock endpoints to apps/dev-server/api/src/routes/
4. Add tests and changeset

Transport Pattern

Adapters use dependency injection for the transport layer:

// Production - uses live URLs
const twilio = new TwilioAdapter({ accountSid: '...', authToken: '...' });

// Development - override transport
const devTransport = new FetchTransport({ baseUrl: 'http://localhost:3000/api' });
const twilio = new TwilioAdapter({ accountSid: '...' }, devTransport);

License

MIT