Skip to content

Commit fbb2a2e

Browse files
artus9033artus9033
committed
docs: add CLI documentation
1 parent 3513646 commit fbb2a2e

7 files changed

Lines changed: 182 additions & 67 deletions

File tree

‎docs/docs/docs/_meta.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@
44
"name": "getting-started",
55
"label": "Getting Started"
66
},
7+
{
8+
"type": "dir",
9+
"name": "cli",
10+
"label": "CLI"
11+
},
712
{
813
"type": "dir",
914
"name": "api-reference",

‎docs/docs/docs/cli/_meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
["introduction", "brownfield", "brownie"]

docs/docs/docs/getting-started/cli.mdx renamed to docs/docs/docs/cli/brownfield.mdx

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,20 @@
1-
# The CLI
1+
# Usage with Brownfield package
22

3-
React Native Brownfield comes with a batteries-included, all-in-one CLI tool called `brownie` that helps you build and publish your React Native app as a framework artifact for iOS (XCFramework) and Android (AAR).
4-
Additionally, it contains CLI utilities for other tools like the `@callstack/brownie` state management tool.
3+
The `brownie` CLI provides utilities for building & packaging artifacts for brownfield projects that use the `@callstack/react-native-brownfield` library.
54

6-
## Publish for iOS
5+
## Usage
6+
7+
```bash
8+
brownie package:android --module-name :BrownfieldLib --variant release # Package AAR with BrownfieldLib module in release variant
9+
brownie publish:android --module-name :BrownfieldLib # Publish all build variants of BrownfieldLib module to Maven local
10+
brownie package:ios --scheme BrownfieldLib --configuration Release # Package XCFramework for BrownfieldLib scheme in Release configuration
11+
brownie codegen --help # Show help
12+
brownie --version # Show version
13+
```
14+
15+
## iOS
16+
17+
### Build for iOS
718

819
Simply run `npx brownie package:ios` to create an XCFramework that you can later integrate into your native iOS app according to other instruction sections below.
920

@@ -18,15 +29,20 @@ Available arguments:
1829
| --extra-params | Custom params that will be passed to xcodebuild command |
1930
| --export-extra-params | Custom params that will be passed to xcodebuild export archive command. Example: `--export-extra-params "-allowProvisioningUpdates"` |
2031
| --export-options-plist | Name of the export options file for archiving. Defaults to: `ExportOptions.plist` |
21-
| --build-folder | Location for iOS build artifacts. Corresponds to Xcode's "-derivedDataPath" |
32+
| --build-folder | Location for iOS build artifacts. Corresponds to Xcode's "-derivedDataPath". By default, the '\<iOS project folder>/build' path will be used. |
2233
| --destination | Define destination(s) for the build. You can pass multiple destinations as separate values or repeated use of the flag. Values: "simulator", "device", or xcodebuild destinations |
2334
| --archive | Create an Xcode archive (IPA) of the build, required for uploading to App Store Connect or distributing to TestFlight |
2435
| --no-install-pods | Skip automatic CocoaPods installation |
2536
| --no-new-arch | Run React Native in legacy async architecture |
2637
| --local | Force local build with xcodebuild |
2738
| --verbose | Enable verbose logging |
2839

29-
## Build for Android
40+
## Android
41+
42+
For Android, building happens in two steps: first, you build (`brownie package:android`) the AAR artifact(s) with your module, in the appropriate build variant(s), and then you `brownie publish:android` them to Maven local.
43+
From there, native applications can consume your library from the local Maven repository.
44+
45+
### Build for Android
3046

3147
To build the artifact for Android without publishing, run `npx brownie package:android --module-name app`.
3248

@@ -38,9 +54,9 @@ Available arguments:
3854
| --module-name | AAR module name |
3955
| --verbose | Enable verbose logging |
4056

41-
## Publish locally for Android
57+
### Publish locally for Android
4258

43-
To publish the `.aar`(s) built beforehand with `npx brownie package:android` to Maven local, which will allow Gradle to be able to load it from Maven local repository, run:
59+
To publish the `.aar`(s) built beforehand with `npx brownie publish:android` to Maven local, which will allow Gradle to be able to load it from Maven local repository, run:
4460

4561
`npx brownie publish:android --module-name app`
4662

‎docs/docs/docs/cli/brownie.mdx‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Usage with Brownie package
2+
3+
The `brownie codegen` CLI command generates Brownie state management library native store types from TypeScript schema.
4+
5+
## Usage
6+
7+
```bash
8+
brownie codegen # Generate for all configured platforms
9+
brownie codegen -p swift # Generate Swift only
10+
brownie codegen --platform kotlin # Generate Kotlin only
11+
brownie codegen --help # Show help for Brownie state management codegen
12+
brownie --version # Show version
13+
```
14+
15+
## Configuration
16+
17+
Add to your app's `package.json`:
18+
19+
```json
20+
{
21+
"brownie": {
22+
"swift": "./ios/Generated/",
23+
"kotlin": "./android/app/src/main/java/com/example/",
24+
"kotlinPackageName": "com.example"
25+
}
26+
}
27+
```
28+
29+
| Field | Required | Description |
30+
| ------------------- | -------- | ----------------------------------------- |
31+
| `swift` | No\* | Output directory for Swift files |
32+
| `kotlin` | No\* | Output directory for Kotlin files |
33+
| `kotlinPackageName` | No | Kotlin package name (extracted from path) |
34+
35+
\*At least one of `swift` or `kotlin` is required.
36+
37+
## Store Definition
38+
39+
Stores are auto-discovered from `*.brownie.ts` files. Define your store shape using module augmentation:
40+
41+
```ts
42+
// BrownfieldStore.brownie.ts
43+
import type { BrownieStore } from '@callstack/brownie';
44+
45+
interface BrownfieldStore extends BrownieStore {
46+
counter: number;
47+
user: string;
48+
isLoading: boolean;
49+
}
50+
51+
declare module '@callstack/brownie' {
52+
interface BrownieStores {
53+
BrownfieldStore: BrownfieldStore;
54+
}
55+
}
56+
```
57+
58+
Multiple stores in same file:
59+
60+
```ts
61+
// Stores.brownie.ts
62+
import type { BrownieStore } from '@callstack/brownie';
63+
64+
interface UserStore extends BrownieStore {
65+
name: string;
66+
email: string;
67+
}
68+
69+
interface SettingsStore extends BrownieStore {
70+
theme: 'light' | 'dark';
71+
notificationsEnabled: boolean;
72+
}
73+
74+
declare module '@callstack/brownie' {
75+
interface BrownieStores {
76+
UserStore: UserStore;
77+
SettingsStore: SettingsStore;
78+
}
79+
}
80+
```
81+
82+
## Generated Output
83+
84+
**Swift** (`Codable` struct with mutable properties):
85+
86+
```swift
87+
struct BrownfieldStore: Codable {
88+
var counter: Double
89+
var isLoading: Bool
90+
var user: String
91+
}
92+
```
93+
94+
**Kotlin** (data class):
95+
96+
```kotlin
97+
package com.example
98+
99+
data class BrownfieldStore (
100+
val counter: Double,
101+
val isLoading: Boolean,
102+
val user: String
103+
)
104+
```
105+
106+
### Store Discovery
107+
108+
1. Recursively finds `*.brownie.ts` files (skips node_modules)
109+
2. Parses `declare module '@callstack/brownie'` blocks using ts-morph
110+
3. Extracts store names from `BrownieStores` interface properties
111+
4. Validates no duplicate store names exist
112+
113+
### Codegen Pipeline
114+
115+
```
116+
*.brownie.ts files (auto-discovered)
117+
│
118+
▼
119+
ts-morph (parse BrownieStores interface)
120+
│
121+
▼
122+
quicktype-typescript-input (schemaForTypeScriptSources)
123+
│
124+
▼
125+
JSON Schema
126+
│
127+
▼
128+
quicktype-core
129+
│
130+
├──▶ Swift (lang: 'swift', mutable-properties: true)
131+
│
132+
└──▶ Kotlin (lang: 'kotlin', framework: 'just-types')
133+
```

‎docs/docs/docs/cli/introduction.mdx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Unified brownfield CLI
2+
3+
React Native Brownfield comes with a batteries-included, all-in-one CLI tool called `brownie` that helps you build and publish your React Native app as a framework artifact for iOS (XCFramework) and Android (AAR).
4+
Additionally, it contains CLI utilities for other tools like the `@callstack/brownie` state management tool.
5+
6+
> ![NOTE]
7+
> The `brownie` CLI is a unified tool serving both the needs of `@callstack/react-native-brownfield` and `@callstack/brownie` packages. The name `brownie` does not mean it is only meant for `@callstack/brownie` state management tool; it is the main CLI for React Native Brownfield as well.
8+
> Technically, the CLI itself is encapsulated in the `@callstack/brownie-cli` package, which is a dependency of both `@callstack/react-native-brownfield` and `@callstack/brownie`. Therefore, installing either of the packages will bring the `brownie` CLI tool to your project.
9+
10+
## Usage
11+
12+
Please refer to the appropriate pages for detailed usage instructions:
13+
14+
- [`@callstack/react-native-brownfield` - Brownfield library commands](./brownfield)
15+
- [`@callstack/brownie` - Brownie state management library commands](./brownie)

‎docs/docs/docs/getting-started/_meta.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
["introduction", "quick-start", "cli", "examples"]
1+
["introduction", "quick-start", "examples"]

‎packages/brownie/ArchitectureOverview.md‎

Lines changed: 3 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -27,17 +27,17 @@ Shared state management between React Native and Native apps (iOS).
2727
└───────────────────┘ └───────────────────────┘
2828
```
2929

30-
## CLI
30+
## CLI command
3131

32-
The `brownie` CLI generates native store types from TypeScript schema.
32+
The `brownie codegen` CLI command generates native store types from TypeScript schema.
3333

3434
### Usage
3535

3636
```bash
3737
brownie codegen # Generate for all configured platforms
3838
brownie codegen -p swift # Generate Swift only
3939
brownie codegen --platform kotlin # Generate Kotlin only
40-
brownie --help # Show help
40+
brownie codegen --help # Show help for Brownie state management codegen
4141
brownie --version # Show version
4242
```
4343

@@ -132,61 +132,6 @@ data class BrownfieldStore (
132132
)
133133
```
134134

135-
## CLI Implementation
136-
137-
### File Structure
138-
139-
```
140-
packages/brownie/scripts/
141-
├── cli.ts # Entry point, parseArgs, command routing
142-
├── config.ts # Config loading from package.json
143-
├── store-discovery.ts # Auto-discover *.brownie.ts files
144-
├── commands/
145-
│ └── codegen.ts # Codegen command with --platform flag
146-
└── generators/
147-
├── swift.ts # Swift Codable generation
148-
└── kotlin.ts # Kotlin data class generation
149-
```
150-
151-
### Store Discovery
152-
153-
1. Recursively finds `*.brownie.ts` files (skips node_modules)
154-
2. Parses `declare module '@callstack/brownie'` blocks using ts-morph
155-
3. Extracts store names from `BrownieStores` interface properties
156-
4. Validates no duplicate store names exist
157-
158-
### Codegen Pipeline
159-
160-
```
161-
*.brownie.ts files (auto-discovered)
162-
│
163-
▼
164-
ts-morph (parse BrownieStores interface)
165-
│
166-
▼
167-
quicktype-typescript-input (schemaForTypeScriptSources)
168-
│
169-
▼
170-
JSON Schema
171-
│
172-
▼
173-
quicktype-core
174-
│
175-
├──▶ Swift (lang: 'swift', mutable-properties: true)
176-
│
177-
└──▶ Kotlin (lang: 'kotlin', framework: 'just-types')
178-
```
179-
180-
### Build
181-
182-
Scripts are compiled with TypeScript during package build:
183-
184-
```bash
185-
yarn build # runs bob build && tsc -p scripts/tsconfig.json
186-
```
187-
188-
Output goes to `lib/scripts/` and is exposed via `bin` field in `package.json`.
189-
190135
## iOS Implementation
191136

192137
### Architecture

0 commit comments

Comments
 (0)