gem-hunter
主要言語: JavaScript
📱🚀A POWERFUL CLI tool to quickly scaffold React Native and Expo TypeScript projects with best practices
A powerful CLI tool to quickly scaffold React Native and Expo TypeScript projects with best practices.
Before installing the CLI, make sure you have the following installed:
The easiest way to use the CLI is with npx, which downloads and runs the latest version without installing it globally:
npx create-voltrn-boilerplate
This method:
Install the CLI globally to use it from anywhere:
npm install -g create-voltrn-boilerplate
After installation, you can run:
create-voltrn-boilerplate
Note: On macOS/Linux, you might need to use sudo:
sudo npm install -g create-voltrn-boilerplate
If you prefer Yarn:
# Global installation yarn global add create-voltrn-boilerplate # Or use with yarn create yarn create voltrn-boilerplate
To verify the CLI is installed correctly:
# If installed globally create-voltrn-boilerplate --version # Or check if the command exists which create-voltrn-boilerplate
If you installed globally, update to the latest version:
npm update -g create-voltrn-boilerplate
Or reinstall:
npm install -g create-voltrn-boilerplate@latest
To remove the globally installed CLI:
npm uninstall -g create-voltrn-boilerplate
If you encounter permission errors during global installation:
# Option 1: Use sudo (not recommended for security reasons) sudo npm install -g create-voltrn-boilerplate # Option 2: Fix npm permissions (recommended) mkdir ~/.npm-global npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH # Add the export line to your ~/.zshrc or ~/.bashrc
If the command is not found after installation:
Check if npm's global bin directory is in your PATH:
npm config get prefix
Add it to your PATH (add to ~/.zshrc or ~/.bashrc):
export PATH="$(npm config get prefix)/bin:$PATH"
Restart your terminal or run:
source ~/.zshrc # or source ~/.bashrc
If you continue having issues with global installation, just use npx - it works without any setup:
npx create-voltrn-boilerplate
Run the CLI and follow the interactive prompts:
npx create-voltrn-boilerplate
You'll be asked:
You can fully customize the screens generated in your project. Enter screen names as a comma-separated list (e.g., Home, Profile, Settings, About). Names are automatically converted to PascalCase.
When not using the authentication flow, you can choose from 4 navigation patterns and assign each screen to a specific navigator:
| Pattern | Description |
|---|---|
| Stack | Simple linear navigation with back/forward buttons |
| Bottom Tabs | Tab bar at the bottom; each screen can go in a Tab or Stack |
| Drawer | Side menu navigation; each screen can go in the Drawer or Stack |
| Tabs + Drawer | Combined tab bar and side menu; each screen can go in Tab, Drawer, or Stack |
For Tabs, Drawer, and Tabs + Drawer patterns, the CLI asks where each screen should go, so you can mix and match freely.
When the authentication flow is enabled, screens are organized into three categories:
PublicHome) - Accessible before loginPrivateHome, Profile, Settings) - Main app screens shown as bottom tabs after loginDetails) - Detail/modal screens accessible from tabsThe auth flow always includes Intro and Login as fixed screens.
When you enable i18n support, the CLI will set up:
Since i18n uses react-native-mmkv which requires native code, Expo projects need to run:
npx expo prebuild
before starting the app. This generates the necessary native code for MMKV to work correctly.
After prebuild, you can start the app normally:
npx expo start -c
When you enable the authentication flow, the CLI will set up:
✅ Auth Client with @forward-software/react-auth
✅ Public Routes
✅ Private Routes (Tab Navigator)
✅ Custom Hooks
useAsyncCallback - Handle async operations with loading statesuseUserCredentials - Manage login form state✅ Full i18n Support
The authentication flow example uses the Platzi Fake Store API as a demo backend. This is a free, public API that provides JWT-based authentication out of the box, making it ideal for testing the auth flow without setting up your own server.
Default login credentials for the example:
Email: john@mail.com
Password: changeme
To connect to your own API, update the configuration in src/env/env.js:
export default { API_URL: "https://your-api.com", ENVIRONMENT: "development" };
Expected endpoints:
POST /v1/auth/login - Returns { access_token, refresh_token }POST /v1/auth/refresh-token - Refreshes tokensGenerated projects with auth flow include a README.md with complete authentication documentation.
your-project/
├── src/
│ ├── screens/ # Screen components
│ ├── components/ # Reusable components
│ ├── i18n/ # Internationalization
│ ├── mmkv/ # MMKV storage setup
│ ├── auth/ # Auth client (if enabled)
│ ├── hooks/ # Custom hooks (if auth enabled)
│ ├── navigators/ # Navigation setup (if auth enabled)
│ └── env/ # Environment config
├── navigation.d.ts # Navigation types
└── app.json # Environment configurations
Environment variables are stored in .env.* files using standard KEY=VALUE format:
.env.development -Development environment.env.staging -Staging environment.env.production -Production environment.env.example -Template with required keys (committed to git)All .env.* files (except .env.example) are gitignored to keep sensitive values out of version control.
Use the following npm scripts to switch between environments:
npm run env:dev # Development npm run env:stage # Staging npm run env:prod # Production
This reads the corresponding .env.* file and generates src/env/env.js (also gitignored), which is imported via the @env/env path alias.
import env from '@env/env'; const apiUrl = env.API_URL; const environment = env.ENVIRONMENT;
.env.* file:# .env.development
API_URL=https://dev-api.example.com
API_KEY=dev-api-key
ENVIRONMENT=development
FEATURE_FLAG=true.env.example so other developers know it's required:# .env.example
API_URL=
API_KEY=
ENVIRONMENT=
FEATURE_FLAG=env.js:npm run env:dev
import env from '@env/env'; const featureEnabled = env.FEATURE_FLAG;
.env.* files are gitignored; use .env.example to document required keyssrc/env/env.js manually -it is generated and will be overwrittenenv:* script before building for a specific environmentThe @env/ path alias is configured in babel.config.js and tsconfig.json, allowing you to import from @env/env instead of using relative paths like ../../env/env.
Every generated project includes automatic splash screen and app icon setup:
A default VoltRN placeholder logo is included so the project works out of the box.
assets/splashscreen.svg (or .png) with your own logo
npm run assets:splash
Customization flags:
| Flag | Description | Default |
|---|---|---|
--background |
Background color (hex) | 1A1A2E |
--logo-width |
Logo width at @1x in dp | 150 |
--platforms |
Target platforms | android,ios |
--dark-background |
Dark mode background (license key required) | - |
--dark-logo |
Dark mode logo path (license key required) | - |
assets/icon.png with your own image (PNG format, minimum 1024x1024px)npm run assets:icons
This generates all required sizes for both iOS and Android automatically.
This project is licensed under the Mozilla Public License 2.0. See the LICENSE file for details.