create-dynamic-app/README.md

CLI tool to generate sample applications using Dynamic's web3 authentication

# Create Dynamic App

![Dynamic Logo](https://cdn.prod.website-files.com/626692727bba3f384e008e8a/66e1b9e7144147903a39ab97_logo-dark.png)

A powerful CLI tool to generate starter applications with [Dynamic's web3 authentication](https://www.dynamic.xyz/). Quickly bootstrap projects using your preferred frameworks, libraries, and blockchain networks.

## Table of Contents

- [Create Dynamic App](#create-dynamic-app)
  - [Table of Contents](#table-of-contents)
  - [Installation](#installation)
  - [Quick Start](#quick-start)
  - [Command-Line Options](#command-line-options)
  - [Features](#features)
  - [Supported Chains](#supported-chains)
  - [Project Options](#project-options)
    - [Frameworks](#frameworks)
    - [Library Options](#library-options)
    - [Package Manager Options](#package-manager-options)
  - [Usage Examples](#usage-examples)
    - [Generate a Next.js App with Specific Options](#generate-a-nextjs-app-with-specific-options)
    - [Generate a React App](#generate-a-react-app)
    - [Generate Projects for Development/Testing](#generate-projects-for-developmenttesting)
  - [Project Structure](#project-structure)
    - [Next.js Project](#nextjs-project)
    - [React Project](#react-project)
  - [Troubleshooting](#troubleshooting)
    - [Common Issues](#common-issues)
  - [Contributing](#contributing)
  - [License](#license)

## Installation

You can use Create Dynamic App directly with npx:

```bash
npx create-dynamic-app my-project-name
```

Or install it globally:

```bash
npm install -g create-dynamic-app
create-dynamic-app my-project-name
```

## Quick Start

```bash
# Create a new project with interactive prompts
npx create-dynamic-app my-web3-app

# Create a project with a specific package manager
npx create-dynamic-app my-web3-app --pm yarn

# Create a Next.js project with Ethereum and Solana support
npx create-dynamic-app my-web3-app --framework nextjs --chains ethereum,solana

# Create a React project with complete configuration
npx create-dynamic-app my-web3-app --framework react --chains ethereum,solana --library viem --wagmi true --pm pnpm
```

## Command-Line Options

Create Dynamic App supports the following command-line options:

| Option                      | Alias | Description                    | Values                                                                           |
| --------------------------- | ----- | ------------------------------ | -------------------------------------------------------------------------------- |
| `--help`                    | `-h`  | Show help information          |                                                                                  |
| `--framework`               | `-f`  | Specify the framework          | `nextjs`, `react`, `react-native`                                                |
| `--pm`, `--package-manager` |       | Specify the package manager    | `npm`, `yarn`, `pnpm`, `bun`                                                     |
| `--library`                 | `-l`  | Specify the Ethereum library   | `viem`, `ethers`                                                                 |
| `--wagmi`                   |       | Use Wagmi with Viem            | `true`, `false`                                                                  |
| `--chains`                  | `-c`  | Comma-separated list of chains | `ethereum`, `solana`, `flow`, `starknet`, `algorand`, `cosmos`, `bitcoin`, `sui` |

If you don't specify options via command line, you'll be prompted to choose interactively.

## Features

- **Multiple Framework Support**: Generate applications using Next.js, React, or React Native
- **Blockchain Flexibility**: Choose from 7 different blockchain networks to include
- **Library Options**: Select your preferred Ethereum libraries (Viem or Ethers.js)
- **Wagmi Integration**: Optional Wagmi support for enhanced React hooks
- **Package Manager Choice**: Select your preferred package manager (npm, yarn, pnpm, or bun)
- **Command-Line Configuration**: Specify all options via command-line flags for automation
- **Ready-to-use Components**: Includes auth components and chain-specific utility methods
- **Dark/Light Mode**: Built-in theme support that respects system preferences

## Supported Chains

The CLI supports the following blockchain networks:

| Chain    | Package                  | Features                                         |
| -------- | ------------------------ | ------------------------------------------------ |
| Ethereum | `@dynamic-labs/ethereum` | Full wallet connection, signing, transactions    |
| Solana   | `@dynamic-labs/solana`   | Wallet connection, signing, program interactions |
| Flow     | `@dynamic-labs/flow`     | Wallet integration and authentication            |
| Starknet | `@dynamic-labs/starknet` | Layer 2 integration and account management       |
| Algorand | `@dynamic-labs/algorand` | Wallet connection and transaction signing        |
| Cosmos   | `@dynamic-labs/cosmos`   | Multi-chain Cosmos ecosystem support             |
| Bitcoin  | `@dynamic-labs/bitcoin`  | Basic Bitcoin wallet connectivity                |
| Sui      | `@dynamic-labs/sui`      | Wallet connection and utility methods            |

## Project Options

### Frameworks

- **Next.js**: Server-side rendering, file-based routing, optimized for production
- **React**: Client-side SPA with Vite configuration
- **React Native**: Mobile application support with Expo

### Library Options

When including Ethereum support, you can choose:

- **Viem**: Modern, lightweight TypeScript library for Ethereum
- **Ethers.js**: Popular, full-featured Ethereum library
- **Wagmi**: React hooks for Ethereum (can be combined with Viem)

### Package Manager Options

You can choose your preferred package manager for installing dependencies:

- **npm**
- **yarn**
- **pnpm**
- **bun**

## Usage Examples

### Generate a Next.js App with Specific Options

```bash
# Interactive creation
npx create-dynamic-app my-next-app

# Create with specific options
npx create-dynamic-app my-next-app --framework nextjs --chains ethereum,solana --library viem --wagmi true --pm yarn
```

### Generate a React App

```bash
# Interactive creation
npx create-dynamic-app my-react-app

# Create with specific options
npx create-dynamic-app my-react-app --framework react --chains ethereum,solana,algorand --library ethers --pm pnpm
```

### Generate Projects for Development/Testing

```bash
# Generate all variations for testing
npm run generate:all

# Create with specific chains for testing
npx create-dynamic-app test-app --chains ethereum,solana,starknet
```

## Project Structure

The generated projects follow best practices for their respective frameworks:

### Next.js Project

```
my-next-app/
├── app/                 # Next.js app directory
│   ├── components/      # React components
│   ├── page.tsx         # Main application page
│   └── layout.tsx       # Root layout
├── lib/                 # Utility functions
│   ├── dynamic.ts       # Dynamic SDK exports
│   ├── providers.tsx    # Context providers
│   └── wagmi.ts         # Wagmi configuration (if selected)
├── public/              # Static assets
└── package.json         # Dependencies and scripts
```

### React Project

```
my-react-app/
├── public/              # Static assets
├── src/                 # Source code
│   ├── App.js           # Main application component
│   ├── Main.js          # Content component
│   ├── Methods.js       # Chain-specific utility methods
│   └── index.js         # Application entry point
└── package.json         # Dependencies and scripts
```

## Troubleshooting

### Common Issues

**Issue**: Error installing dependencies with npm
**Solution**: Try using `--legacy-peer-deps` flag or specify a different package manager:

```bash
# Using the CLI
npx create-dynamic-app my-app --pm yarn

# Or manually
cd my-dynamic-project
npm install --legacy-peer-deps
```

**Issue**: Conflicts with Solana dependencies
**Solution**: The generator adds necessary overrides. If you have issues, manually set:

```json
"overrides": {
  "rpc-websockets": "7.10.0",
  "@solana/web3.js": "1.91.6"
}
```

**Issue**: Environment ID is missing
**Solution**: Replace the placeholder in providers.tsx/App.js:

```typescript
environmentId: "YOUR_ENVIRONMENT_ID", // Get from Dynamic dashboard
```

## Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and linting (`npm run lint && npm test`)
5. Commit your changes (`git commit -m 'Add some amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## License

ISC License - see the [LICENSE](LICENSE) file for details.