Skip to content

README.md

Latest commit

 

History

History
339 lines (250 loc) · 10.5 KB

README.md

File metadata and controls

339 lines (250 loc) · 10.5 KB

React Native TypeScript Library Starter

CI npm version npm downloads License: MIT Platform TypeScript

A modern, production-ready starter for building React Native TypeScript libraries. Ships with dual CJS/ESM output, full test coverage, automated releases, and AI-ready project conventions out of the box.

Features

  • react-native-builder-bob — dual CJS + ESM + TypeScript declarations
  • Strict TypeScript — noImplicitAny, strictNullChecks, noUnusedLocals
  • Jest + @testing-library/react-native — full test suite with coverage thresholds
  • ESLint + Prettier — consistent code style, enforced on commit via lint-staged
  • Husky + commitlint — conventional commit enforcement
  • semantic-release — automated versioning, changelog, and npm publish
  • GitHub Actions — CI pipeline (typecheck + lint + test + build) and release pipeline
  • AI-Ready — AGENTS.md, Cursor rules, and full TSDoc on every export
  • Example component and hook — reference implementations to clone from

Quick Start

1. Clone and install

git clone https://github.com/WrathChaos/react-native-typescript-library-starter.git my-library
cd my-library
npm install

2. Set up git hooks

npm run husky:setup

3. Configure the library

Run the interactive setup wizard. It walks through every field one by one, shows a preview of all planned changes, and asks for confirmation before writing anything:

npm run setup

The wizard will ask for:

  • Package name — your npm name (e.g. react-native-my-library)
  • Description — one sentence
  • GitHub username / org — used to build repo URLs automatically
  • GitHub repository name — defaults to your package name
  • Author name & email
  • License — MIT, Apache-2.0, ISC, GPL-3.0, or Unlicensed
  • Keywords — optional, comma-separated extras

After confirmation it updates package.json, README.md, AGENTS.md, and CONTRIBUTING.md in one go.

4. Replace the example code

The src/ folder contains a fully-typed example component and hook. Use them as reference, then replace with your own:

src/
├── components/MyComponent/   → replace with your component
├── hooks/useMyHook.ts        → replace with your hook
└── index.ts                  → update exports

5. Build and verify

npm run build      # outputs to lib/
npm run typecheck  # type-check without emitting
npm test           # run the test suite

Project Structure

react-native-typescript-library-starter/
├── src/                          # ALL source code
│   ├── index.ts                  # Public API entry point
│   ├── components/
│   │   └── MyComponent/
│   │       ├── MyComponent.tsx
│   │       ├── MyComponent.types.ts
│   │       └── index.ts
│   ├── hooks/
│   │   └── useMyHook.ts
│   ├── types/
│   │   └── index.ts
│   └── __tests__/
│       ├── MyComponent.test.tsx
│       └── useMyHook.test.ts
├── lib/                          # Generated by bob (git-ignored)
├── .github/workflows/
│   ├── ci.yml                    # PR checks
│   └── release.yml               # Publish pipeline
├── AGENTS.md                     # AI agent instructions
├── CONTRIBUTING.md
├── CHANGELOG.md
├── package.json
├── tsconfig.json
├── tsconfig.build.json
└── babel.config.js

Scripts

Command Description
npm run build Build library to lib/ via bob
npm run typecheck Type-check without emitting
npm run lint Run ESLint with colored output and auto-fix
npm run lint:ci ESLint without spinner (for CI)
npm run prettier Format source files
npm run prettier:ci Check formatting (for CI)
npm test Run Jest tests
npm run test:watch Jest in watch mode
npm run test:coverage Jest with coverage report

Build Output

react-native-builder-bob produces three output targets inside lib/:

Output Path Used by
CommonJS lib/commonjs/ Node.js, bundlers with require()
ESM lib/module/ Modern bundlers, tree-shaking
TypeScript lib/typescript/ Type declarations for consumers

The package.json exports field routes consumers to the correct output automatically.

Example Component

import { MyComponent } from "your-library";

export default function App() {
  return (
    <MyComponent
      title="Hello World"
      description="A fully-typed example component."
      enableButton
      buttonText="Tap me"
      onPress={() => console.log("pressed")}
    />
  );
}

MyComponent Props

Prop Type Default Description
title string — Primary title text (required)
description string — Optional description below title
enableButton boolean false Renders an action button
buttonText string "Press me" Button label
onPress () => void — Button press callback
style StyleProp<ViewStyle> — Root container style override
titleStyle StyleProp<TextStyle> — Title text style override
descriptionStyle StyleProp<TextStyle> — Description text style override
buttonStyle StyleProp<ViewStyle> — Button container style override
buttonTextStyle StyleProp<TextStyle> — Button label style override
accessibilityLabel string title Accessibility label for the container
testID string "my-component" Test ID for querying in tests

Example Hook

import { useMyHook } from "your-library";

function Counter() {
  const { count, increment, decrement, reset, isAtMax, isAtMin } = useMyHook({
    initialValue: 0,
    max: 10,
    min: 0,
    step: 1,
  });

  return (
    <View>
      <Text>{count}</Text>
      <Button title="+" onPress={increment} disabled={isAtMax} />
      <Button title="-" onPress={decrement} disabled={isAtMin} />
      <Button title="Reset" onPress={reset} />
    </View>
  );
}

useMyHook Options

Option Type Default Description
initialValue number 0 Starting counter value
max number — Upper bound (no limit if omitted)
min number 0 Lower bound
step number 1 Increment/decrement amount

useMyHook Return

Key Type Description
count number Current counter value
increment () => void Increment by step
decrement () => void Decrement by step
reset () => void Reset to initialValue
isAtMax boolean true when count >= max
isAtMin boolean true when count <= min

Testing

Tests use Jest and @testing-library/react-native.

npm test                 # run all tests
npm run test:coverage    # with coverage report

Coverage thresholds are enforced in package.json:

  • Branches: 70%
  • Functions / Lines / Statements: 80%

Commit Conventions

This project enforces Conventional Commits via commitlint:

feat: add MyButton component
fix: correct accessibility role
test: add boundary cases for useMyHook
docs: update README with new props
chore: upgrade dependencies

Commits trigger automatic versioning via semantic-release:

  • fix → patch release
  • feat → minor release
  • feat with BREAKING CHANGE footer → major release

CI / CD

CI Pipeline (.github/workflows/ci.yml)

Runs on every push and pull request to main:

  1. Typecheck — tsc --noEmit
  2. Lint — ESLint + Prettier check
  3. Test — Jest with coverage
  4. Build — bob build (only runs after all checks pass)

Release Pipeline (.github/workflows/release.yml)

Runs on push to main after CI passes:

  1. Run full test suite
  2. Build library
  3. semantic-release → bump version, update CHANGELOG.md, publish to npm, create GitHub release

Required secrets: NPM_TOKEN (in your GitHub repo settings).

AI / LLM Usage

This starter is designed to be AI-friendly:

  • AGENTS.md — read this file first when working with an AI agent. It contains the full directory map, all runnable commands, conventions, naming rules, and do/don'ts.
  • .cursor/rules/library-conventions.mdc — Cursor AI rules that automatically enforce component/hook patterns.
  • TSDoc everywhere — every exported function, component, prop, and type has @param, @returns, and @example documentation. This maximises AI autocomplete quality.
  • Strict TypeScript — strict mode produces accurate types that AI tools can reason about reliably.
  • Conventional Commits — predictable commit history helps AI tools summarize changes and generate release notes.

Using with Cursor

The .cursor/rules/library-conventions.mdc rule is auto-applied to all src/**/*.ts and src/**/*.tsx files. It enforces component structure, hook patterns, and TSDoc requirements.

Using with Claude / ChatGPT

Paste the contents of AGENTS.md into the system prompt or the start of a conversation for best results.

Peer Dependencies

"peerDependencies": {
  "react": ">=17.0.0",
  "react-native": ">=0.70.0"
}

Contributing

See CONTRIBUTING.md for the full guide.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.

Author

FreakyCoder — kurayogun@gmail.com
freakycoder.com