> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nativedesktop.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Project
> Initialize a new Native Desktop project
The `create` command initializes a new Native Desktop project with all necessary configuration files, dependencies, and project structure. This command provides an interactive setup process to customize your project.
## Prerequisites
Before creating a Native Desktop project, ensure you have:
* **Node.js** (version 16 or higher)
* **npm** or **yarn** package manager
* An **empty directory** for your project
The CLI will only create projects in empty directories. If your directory contains any files or folders, the command will fail with an error.
## Basic Usage
To create a new project, navigate to an empty directory and run:
```shellscript theme={null}
native-desktop create
```
It is not possible to set a custom path; the recommended workflow is to create a new folder and run the CLI from there.
## Interactive Setup
The `create` command launches an interactive setup wizard that guides you through the project configuration process.
### Step 1: Select Project Type
The CLI first prompts you to select a project type:
```shellscript theme={null}
? Select the project type: (Use arrow keys)
❯ Empty Project
Manual Project
```
#### Available Project Types
Creates a new project with minimal default settings, perfect for starting from scratch. This option provides:
* Basic project structure
* Essential configuration files
* Minimal boilerplate code
* Quick setup process
**Best For**: Beginners or simple applications
Creates a fully customizable project with comprehensive default settings. This option includes:
* Complete project structure
* Advanced configuration options
* Development tools setup
* Extended boilerplate code
**Best For**: Advanced users who want complete control and manual configuration
### Step 2: Project Configuration
After selecting the project type, you'll be prompted to provide project details:
#### Project Name
```shellscript theme={null}
? Enter a name for your project (e.g. "My App"):
```
* **Required**: Yes
* **Min Length**: 2 characters
* **Max Length**: 100 characters
* **Example**: `My Awesome App`
This is the human-readable name displayed to users.
#### Project Version
```shellscript theme={null}
? Enter the initial version of your project (e.g. "1.0.0"):
```
* **Required**: Yes
* **Default**: `1.0.0`
* **Format**: Semantic versioning (MAJOR.MINOR.PATCH)
* **Example**: `1.0.0`, `0.1.0`, `2.3.4`
The version must follow [Semantic Versioning](https://semver.org/) format: `MAJOR.MINOR.PATCH`
#### Package Identifier
```shellscript theme={null}
? Enter the package identifier (e.g. "my-app"):
```
* **Required**: Yes
* **Auto-generated**: Based on project name (if not provided)
* **Min Length**: 2 characters
* **Max Length**: 214 characters
* **Format**: Lowercase letters, numbers, and hyphens only
* **Restrictions**: Cannot start or end with a hyphen
* **Example**: `my-awesome-app`
This identifier is used internally and in package manifests.
#### Project Description
```shellscript theme={null}
? Enter a brief description of your project (e.g. "A task management app for teams"):
```
* **Required**: No
* **Default**: `A NativeDesktop Application`
* **Max Length**: 500 characters
* **Example**: `A powerful task management application for remote teams`
#### Author Information
```shellscript theme={null}
? Enter the author name (e.g. "Jane Doe "):
```
* **Required**: Yes
* **Default**: `NativeDesktop`
* **Max Length**: 200 characters
* **Format**: Name or Name with email in angle brackets
* **Example**: `John Smith `
You can include an email address in angle brackets: `Jane Doe `
#### Project URL
```shellscript theme={null}
? Enter your project's domain URL (e.g. "https://nativedesktop.com"):
```
* **Required**: Yes
* **Format**: Valid HTTP or HTTPS URL
* **Example**: `https://example.com`
This URL is used in project metadata and application information.
## Complete Example
Here's a complete example of the project creation flow:
```shellscript theme={null}
$ native-desktop create
✔ Select the project type: Manual Project
✔ Enter a name for your project (e.g. "My App"): Task Manager Pro
✔ Enter the initial version of your project (e.g. "1.0.0"): 1.0.0
✔ Enter the package identifier (e.g. "my-app"): task-manager-pro
✔ Enter a brief description of your project (e.g. "A task management app for teams"):
A professional task management application with team collaboration features
✔ Enter the author name (e.g. "Jane Doe "):
Jane Smith
✔ Enter your project's domain URL (e.g. "https://nativedesktop.com"):
https://taskmanager.com
Creating project...
✓ Created project structure
✓ Generated configuration files
✓ Installing dependencies...
✓ Project created successfully!
Next steps:
1. Start development: native-desktop run
2. Build for production: native-desktop build --target dmg
```
## Generated Project Structure
After creation, your project will have the following structure:
```text theme={null}
project-directory/
├── src/ # Source code directory
├── package.json # Project dependencies and scripts
├── native-desktop.config.json5 # Native Desktop configuration
├── tsconfig.json # TypeScript configuration
├── .eslintrc.json # ESLint configuration
├── .prettierrc # Prettier configuration
├── .gitignore # Git ignore rules
└── .npmrc # npm configuration
```
### Configuration Files
The `create` command generates several configuration files:
The main configuration file for your Native Desktop application. Contains build settings, application metadata, and platform-specific options.
TypeScript compiler configuration with recommended settings for Native Desktop projects.
ESLint configuration for code quality checking with Native Desktop best practices.
Prettier configuration for consistent code formatting across the project.
## Post-Creation Steps
After creating your project, you can:
### 1. Install Dependencies
If dependencies weren't automatically installed:
```shellscript theme={null}
npm install
```
### 2. Start Development
Run your application in development mode:
```shellscript theme={null}
native-desktop run
```
### 3. Explore Configuration
Review and customize the generated `native-desktop.config.json5` file to suit your needs.
### 4. Add Your Code
Start building your application in the `src/` directory.
## Validation Rules
The `create` command validates all inputs to ensure a valid project configuration:
| Field | Validation |
| ------------------ | -------------------------------------------------------------------------------- |
| Project Name | Required, 2-100 characters |
| Version | Must follow semantic versioning (e.g., 1.0.0) |
| Package Identifier | Required, 2-214 characters, lowercase, hyphens only, no leading/trailing hyphens |
| Description | Optional, max 500 characters |
| Author | Required, max 200 characters, valid email format if provided |
| URL | Required, valid HTTP/HTTPS URL |
## Common Issues
**Error**: `NativeDesktop can only create new projects in an empty folder.`
**Solution**: Ensure your directory is completely empty. Remove all files and folders, including hidden files.
```shellscript theme={null}
# Create a new empty directory
mkdir my-project
cd my-project
native-desktop create
```
**Error**: `Package identifier must contain only lowercase letters, numbers, and hyphens`
**Solution**: Use only lowercase letters, numbers, and hyphens. Avoid spaces, uppercase letters, and special characters.
**Valid**: `my-app-123` **Invalid**: `My App`, `my_app`, `MyApp!`
**Error**: `Version must follow semantic versioning format (e.g., 1.0.0)`
**Solution**: Use the semantic versioning format with three numbers separated by dots.
**Valid**: `1.0.0`, `0.1.0`, `2.3.4` **Invalid**: `1.0`, `v1.0.0`, `1.0.0-beta`
**Error**: `URL must start with http:// or https://`
**Solution**: Provide a complete URL including the protocol.
**Valid**: `https://example.com`, `http://localhost:3000` **Invalid**: `example.com`, `www.example.com`
## Best Practices
Use descriptive, lowercase package identifiers with hyphens (kebab-case)
Start with `1.0.0` for production-ready apps, or `0.1.0` for early development
Choose "Empty Project" for learning, "Manual Project" for production apps
Include a meaningful description to help other developers understand your project