solid-tma

SolidJS component library for building Telegram Mini Apps (TMA).

Install

bun add solid-tma

solid-tma declares its runtime dependencies (solid-js, @telegram-apps/sdk-solid, sass, swiper, vite, vite-plugin-solid, etc.) as peer dependencies — install whichever ones your app actually uses. This is intentional: it guarantees your app and the library always share the exact same solid-js instance, so it's never bundled twice.

Import map

| Subpath | Contents | |---|---| | solid-tma/components | UI, TMA chrome, portals, misc glue components | | solid-tma/hooks | Solid primitives (useX) | | solid-tma/providers | Context providers (Theme, Settings, Motion, Direction, Translation, Modal) | | solid-tma/layouts | Page layout components | | solid-tma/utils | Pure helper functions | | solid-tma/config | Build-time config helpers (e.g. purgecss options) | | solid-tma/postcss | PostCSS plugin helpers | | solid-tma/style | Compiled CSS design tokens/utilities — import once at your app root |

Each subpath resolves two ways, both avoiding a duplicate solid-js:

• Solid-aware bundlers (Vite + vite-plugin-solid, SolidStart) resolve the "solid" export condition straight to raw .tsx source, so it's compiled by your own toolchain with full tree-shaking/SSR support.
• Any other bundler falls back to a precompiled dist/ build with all peer dependencies externalized and component CSS auto-injected at runtime — same zero-extra-import DX, no vite-plugin-solid required.

Quick start

import { createSignal } from "solid-js";
import "solid-tma/style";
import {
	ModalProvider,
	ModalsPortal,
	SettingsProvider,
	SymbolsPortal,
	TMAGuard,
	ToastsPortal,
} from "solid-tma/components";
import {
	DirectionProvider,
	MotionProvider,
	ThemeProvider,
	TranslationProvider,
} from "solid-tma/providers";
import {
	createDirectionProvider,
	createMotionProvider,
	createTranslationProvider,
} from "solid-tma/utils";

// See skill/SKILL.md (or `.claude/skills/solid-tma-consumer` after copying it
// into your project) for the full provider composition + TMAGuard example.

For the complete, working composition (provider order, TMAGuard gating, portals), see src/kitchensink/App.tsx in this repo, or copy the shipped skill file into your own project — see AI agent skill below.

AI agent skill

This package ships an agent-facing skill file describing how to integrate it correctly (provider order, peer deps, TMAGuard, portals, import map). After installing, copy it into your project so Claude Code (or another skill-aware agent) can use it:

mkdir -p .claude/skills/solid-tma
cp node_modules/solid-tma/skill/SKILL.md .claude/skills/solid-tma/SKILL.md

Publishing (maintainers)

Versioning is manual semver, no changesets:

1. bun run lint
2. npm version patch|minor|major — bumps package.json and creates a git tag
3. npm publish — prepublishOnly automatically runs lint + rebuilds dist/ (bun run build:lib), so a stale/broken dist can never ship
4. git push --follow-tags once you're ready

bun run build:lib builds the publishable dist/ (dual-output JS + .d.ts + style.css) via vite.lib.config.ts. It's separate from bun run build, which builds the kitchensink demo app and is unrelated to publishing.

Development

• bun run dev — kitchensink demo app (src/kitchensink), the library's visual test suite
• bun run dev:mock — same app on a dedicated port with a mocked Telegram environment (used by Playwright)
• bun run lint — typecheck + biome check/fix
• bun run test:e2e — Playwright suite against the mocked Telegram environment

License

MIT © Erfan Mola