CONTRIBUTING.md 5.8 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
**Important:** Before starting work on a pull request, you must first [open an issue](https://github.com/stevedylandev/bhvr/issues/new) describing your proposed change and wait for it to be reviewed and approved. PRs without a corresponding approved issue will be closed.
18
19
1.  Fork the repository and create your branch from `main`.
20
2.  Run `bun install` to install the dependencies.
21
3.  Make your changes.
22
4.  Run `bun run build` to make sure your changes build correctly.
23
5.  Use `bun dist` to run the CLI and test your new changes.
24
6.  Use `bun lint` and `bun format` to apply Biome formatting and lint checking.
25
7.  Use `bun test` to run unit tests. Depending on your PR consider adding tests.
26
8.  Issue that pull request!
27
28
## Repo Structure
29
30
`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.
31
32
### Project Architecture
33
34
```
35
src/
36
├── commands/           # CLI command handlers
37
│   └── create.ts      # Main create command implementation
38
├── installers/        # Extension installers
39
│   ├── react-router.ts      # React Router setup
40
│   ├── rpc.ts              # RPC integration
41
│   ├── tanstack-query.ts   # TanStack Query setup
42
│   └── tanstack-router.ts  # TanStack Router setup
43
├── lib/               # Core functionality
44
│   ├── create-project.ts    # Main project creation orchestrator
45
│   ├── scaffold-template.ts # Template downloading and setup
46
│   ├── install-dependencies.ts
47
│   ├── prompt-for-options.ts
48
│   └── ...
49
├── templates/extras/  # Template variations for extensions
50
│   └── client/
51
│       ├── src/App.tsx/     # App.tsx variants for different combinations
52
│       ├── src/main.tsx/    # Entry point variants
53
│       ├── src/components/  # Component variants
54
│       └── vite.config.ts/  # Vite config variants
55
├── utils/             # Utility functions
56
│   ├── name-generator.ts    # Generates template file names
57
│   ├── templates.ts         # Template configurations
58
│   └── constants.ts
59
└── types.ts           # TypeScript definitions
60
```
61
62
### How Extensions Work
63
64
Extensions in create-bhvr follow a modular architecture where each extension has:
65
66
1. **An Installer** (`src/installers/*.ts`) that handles:
67
   - Adding dependencies via `addPackageDependency()`
68
   - Copying appropriate template files using the `nameGenerator()` utility
69
   - Managing configuration changes
70
71
2. **Template variants** (`src/templates/extras/`) that provide:
72
   - Pre-configured code for different extension combinations
73
   - File variants named using a convention like `App-with-rpc-tailwind-tanstackquery.tsx`
74
   - Smart file selection based on enabled options
75
76
#### Adding New Extensions
77
78
To add a new extension (e.g., "myextension"):
79
80
1. **Create the installer** (`src/installers/myextension.ts`):
81
   ```typescript
82
   export const myExtensionInstaller = async (options: Required<ProjectOptions>) => {
83
     // Install dependencies
84
     await addPackageDependency({
85
       dependencies: ["my-package"],
86
       target: "client",
87
       projectName: options.projectName,
88
     });
89
90
     // Copy appropriate template files
91
     const selectedTemplate = nameGenerator("App.tsx", {
92
       myExtension: options.myExtension,
93
       // ... other options
94
     });
95
   };
96
   ```
97
98
2. **Add template variants** in `src/templates/extras/client/src/`:
99
   - Create files like `App-with-myextension.tsx`
100
   - Support all possible combinations like `App-with-myextension-tailwind.tsx`
101
102
3. **Update types** (`src/types.ts`):
103
   ```typescript
104
   export type ProjectOptions = {
105
     // ... existing options
106
     myExtension?: boolean;
107
   };
108
   ```
109
110
4. **Update the name generator logic** (`src/utils/name-generator.ts`) if needed for special naming rules.
111
112
#### Template File Naming Convention
113
114
The `nameGenerator()` utility creates file names based on enabled options:
115
- Base file: `App.tsx`
116
- With TanStack Query: `App-with-tanstackquery.tsx`
117
- Multiple extensions: `App-with-rpc-tailwind-tanstackquery.tsx`
118
119
Options are sorted alphabetically to ensure consistent naming.
120
121
#### Updating GitHub Actions
122
123
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`.
124
125
## License
126
127
By contributing, you agree that your contributions will be licensed under its MIT License.