CONTRIBUTING.md 5.5 K raw
1
# Contributing to create-bhvr
2
3
First off, thank you for considering contributing to `create-bhvr`.
4
5
## How Can I Contribute?
6
7
### Reporting Bugs
8
9
If you find a bug, please make sure the bug has not already been reported by searching on GitHub under [Issues](https://github.com/stevedylandev/bhvr/issues). If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/stevedylandev/bhvr/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
10
11
### Suggesting Enhancements
12
13
If you have an idea for an enhancement, please make sure the enhancement has not already been suggested by searching on GitHub under [Issues](https://github.com/stevedylandev/bhvr/issues). If you're unable to find an open issue addressing the suggestion, [open a new one](https://github.com/stevedylandev/bhvr/issues/new). Be sure to include a **title and clear description** of the enhancement you're suggesting.
14
15
### Submitting a Pull Request
16
17
1.  Fork the repository and create your branch from `main`.
18
2.  Run `bun install` to install the dependencies.
19
3.  Make your changes.
20
4.  Run `bun run build` to make sure your changes build correctly.
21
5.  Use `bun dist` to run the CLI and test your new changes.
22
6.  Use `bun lint` and `bun format` to apply Biome formatting and lint checking.
23
7.  Use `bun test` to run unit tests. Depending on your PR consider adding tests.
24
8.  Issue that pull request!
25
26
## Repo Structure
27
28
`create-bhvr` is a CLI tool that generates full-stack TypeScript projects using the Bun + Hono + Vite + React (BHVR) stack. The tool scaffolds projects from GitHub templates and allows users to add various extensions like TanStack Query, React Router, and more.
29
30
### Project Architecture
31
32
```
33
src/
34
├── commands/           # CLI command handlers
35
│   └── create.ts      # Main create command implementation
36
├── installers/        # Extension installers
37
│   ├── react-router.ts      # React Router setup
38
│   ├── rpc.ts              # RPC integration
39
│   ├── tanstack-query.ts   # TanStack Query setup
40
│   └── tanstack-router.ts  # TanStack Router setup
41
├── lib/               # Core functionality
42
│   ├── create-project.ts    # Main project creation orchestrator
43
│   ├── scaffold-template.ts # Template downloading and setup
44
│   ├── install-dependencies.ts
45
│   ├── prompt-for-options.ts
46
│   └── ...
47
├── templates/extras/  # Template variations for extensions
48
│   └── client/
49
│       ├── src/App.tsx/     # App.tsx variants for different combinations
50
│       ├── src/main.tsx/    # Entry point variants
51
│       ├── src/components/  # Component variants
52
│       └── vite.config.ts/  # Vite config variants
53
├── utils/             # Utility functions
54
│   ├── name-generator.ts    # Generates template file names
55
│   ├── templates.ts         # Template configurations
56
│   └── constants.ts
57
└── types.ts           # TypeScript definitions
58
```
59
60
### How Extensions Work
61
62
Extensions in create-bhvr follow a modular architecture where each extension has:
63
64
1. **An Installer** (`src/installers/*.ts`) that handles:
65
   - Adding dependencies via `addPackageDependency()`
66
   - Copying appropriate template files using the `nameGenerator()` utility
67
   - Managing configuration changes
68
69
2. **Template variants** (`src/templates/extras/`) that provide:
70
   - Pre-configured code for different extension combinations
71
   - File variants named using a convention like `App-with-rpc-tailwind-tanstackquery.tsx`
72
   - Smart file selection based on enabled options
73
74
#### Adding New Extensions
75
76
To add a new extension (e.g., "myextension"):
77
78
1. **Create the installer** (`src/installers/myextension.ts`):
79
   ```typescript
80
   export const myExtensionInstaller = async (options: Required<ProjectOptions>) => {
81
     // Install dependencies
82
     await addPackageDependency({
83
       dependencies: ["my-package"],
84
       target: "client",
85
       projectName: options.projectName,
86
     });
87
88
     // Copy appropriate template files
89
     const selectedTemplate = nameGenerator("App.tsx", {
90
       myExtension: options.myExtension,
91
       // ... other options
92
     });
93
   };
94
   ```
95
96
2. **Add template variants** in `src/templates/extras/client/src/`:
97
   - Create files like `App-with-myextension.tsx`
98
   - Support all possible combinations like `App-with-myextension-tailwind.tsx`
99
100
3. **Update types** (`src/types.ts`):
101
   ```typescript
102
   export type ProjectOptions = {
103
     // ... existing options
104
     myExtension?: boolean;
105
   };
106
   ```
107
108
4. **Update the name generator logic** (`src/utils/name-generator.ts`) if needed for special naming rules.
109
110
#### Template File Naming Convention
111
112
The `nameGenerator()` utility creates file names based on enabled options:
113
- Base file: `App.tsx`
114
- With TanStack Query: `App-with-tanstackquery.tsx`
115
- Multiple extensions: `App-with-rpc-tailwind-tanstackquery.tsx`
116
117
Options are sorted alphabetically to ensure consistent naming.
118
119
#### Updating GitHub Actions
120
121
To make sure your new addition to extensions work, please add your combination to `.github/workflows/test-cli-options.yml` to make sure it does not break other builds. In order to do this you need to add your combination to the matrix and make sure a flag is included in `src/index.ts`.
122
123
## License
124
125
By contributing, you agree that your contributions will be licensed under its MIT License.