Nextellar

Nextellar is a one-step CLI toolkit that bootstraps a production-ready Next.js + TypeScript application with built-in Stellar blockchain support. Scaffold a full-stack dApp starter—complete with wallet connection, payment hooks, smart-contract integration, UI components, and best-practice defaults—so you can focus on features, not setup.

---

🚀 Features

• One-step scaffold

  npx nextellar my-app

• Built-in Stellar support
  • Horizon & Soroban endpoints configured
  • Wallet-adapter plugin system (Freighter, XBull, Ledger, etc.)
• React Hooks
  • useStellarAccount(), useStellarPayment(), useTrustlines(), useTransactionHistory(), useSorobanContract()
• UI Components
  • <WalletConnectButton>, <BalanceDisplay>, <SendForm>, <ReceiveForm>, <TransactionList>, <NetworkSwitcher>, <TransactionStatusBadge>
• Opinionated stack
  • Next.js (v13+ App Router) + TypeScript
  • Tailwind CSS + shadcn/ui
  • ESLint, Prettier, Jest + React Testing Library
  • Storybook for component previews
  • GitHub Actions CI for linting, testing, and build
• 🔒 Security First
  • Automated dependency auditing (daily)
  • Strict severity gates (fail on critical/high)
  • Dependabot auto-updates for security patches
  • CodeQL static analysis
  • See SECURITY.md for details

---

📦 Installation

No global install required:

npx nextellar my-app
cd my-app
npm install
npm run dev

Or install globally:

npm install -g nextellar
nextellar my-app

---

⚙️ CLI Usage

Usage: nextellar <project-name> [options]

Options:
  -t, --typescript         Generate a TypeScript project (default)
  -j, --javascript         Generate a JavaScript project
  --template <name>        Starter to scaffold (default, minimal, defi)
  --horizon-url <url>      Override default Horizon endpoint
  --soroban-url <url>      Override default Soroban RPC endpoint
  -w, --wallets <list>     Comma-separated list of wallet adapters
  -d, --defaults           Skip prompts and use defaults
  --skip-install           Skip dependency installation after scaffolding
  --package-manager <pm>   Choose package manager (npm, yarn, pnpm)
  --install-timeout <ms>   Timeout in ms for package install (default: 1200000 / 20 minutes)
  -v, --version            Show CLI version
  -h, --help               Show help text

---

🧩 Templates

--template <name> selects which starter to scaffold. It defaults to default when omitted.

Template	Description	TypeScript	JavaScript
default	Full starter: wallet provider, network switcher, balances, transaction history	✅	✅
minimal	Bare starter: wallet connection only, no extra UI	✅	❌
defi	DeFi starter: swap, liquidity pool and price-feed components	✅	✅

npx nextellar my-app                        # default template, TypeScript
npx nextellar my-app --template minimal     # minimal starter
npx nextellar my-app --template defi        # DeFi starter
npx nextellar my-app --template defi -j     # DeFi starter, JavaScript

An unrecognised name fails before anything is written, and the error lists every valid option:

$ npx nextellar my-app --template nope
Unknown template "nope". Available templates: default, minimal, defi.

minimal has no JavaScript variant yet. Asking for one reports which templates do:

$ npx nextellar my-app --template minimal --javascript
Template "minimal" is not available for JavaScript yet. Templates with a JavaScript variant: default, defi.

Soroban smart contracts are added with --with-contracts, not with --template. The two flags compose: --template defi --with-contracts.

---

📁 Project Structure

my-app/
├── public/                     # Static assets (logos, icons)
├── src/
│   ├── app/                    # Next.js App Router (Layouts & Pages)
│   ├── components/             # Reusable UI components (WalletButton, etc)
│   ├── contexts/               # React Contexts (WalletProvider)
│   ├── hooks/                  # Custom Stellar hooks (useStellarAccount, etc)
│   └── lib/                    # Core logic and SDK initializations
├── tailwind.config.ts          # Styling configuration
├── tsconfig.json               # TypeScript configuration
├── package.json                # Project dependencies
└── README.md                   # You are here!

---

📖 Documentation

Full API reference, guides, and examples live at:
🔗 https://docs.nextellar.dev

Telemetry and privacy details:
🔗 docs/telemetry.md

Per-template bundle analysis and size budgets:
🔗 docs/bundle-budgets.md

Deployment bundle guide (nextellar deploy):
🔗 docs/deploy-guide.md

Network and environment configuration (Horizon/Soroban, testnet/mainnet, NetworkSwitcher):
🔗 docs/network-environment-guide.md

Soroban contracts overlay guide (--with-contracts):
🔗 docs/soroban-contracts-overlay-guide.md

---

🤝 Contributing

We welcome your help! Please read CONTRIBUTING.md for:

• Issue & PR workflow
• Branch naming conventions
• Testing & linting guidelines

---

📜 License

MIT © 2025 Nextellar Labs