npm package: @init-spark/umbraco
Description: Init Spark Umbraco is a CLI tool for quickly setting up Umbraco projects with frontend technologies like Vue (or Nuxt), React (or Next), and Gulp. It automates the installation of .NET SDK, Umbraco CMS, initializes a Git repo, and creates a solution file,
Author: João Borges
Latest version: 0.0.14

# Init-Spark Umbraco

<div align="center">

![NPM Version](https://img.shields.io/npm/v/@init-spark/umbraco)
![NPM Downloads](https://img.shields.io/npm/dm/@init-spark/umbraco)
![License](https://img.shields.io/npm/l/@init-spark/umbraco)
![Node Version](https://img.shields.io/node/v/@init-spark/umbraco)

**A powerful CLI tool for scaffolding Umbraco CMS projects with modern frontend frameworks**

[Quick Start](#quick-start) • [Features](#features) • [Documentation](#getting-started)

</div>

---

## 📋 Description

Init-Spark Umbraco is a comprehensive CLI tool that streamlines the setup of Umbraco CMS projects with integrated modern frontend technologies. It automates the entire project initialization process, including:

- ✅ .NET SDK installation and configuration
- ✅ Umbraco CMS installation
- ✅ Frontend framework setup (Vue/Nuxt, React/Next, or Gulp)
- ✅ Git repository initialization
- ✅ Solution file creation
- ✅ Pre-configured project structure with best practices

## 🚀 Quick Start

Create a new Umbraco project with a single command:

```bash
npx @init-spark/umbraco
```

Follow the interactive prompts to configure your project:

1. Choose your project name
2. Select Umbraco version
3. Pick your frontend technology (Vue, React, or Gulp)
4. Configure additional options

## ✨ Features

- **🔧 Zero Configuration**: Get started immediately without manual setup
- **🎨 Multiple Frontend Options**: Choose between Vue/Nuxt, React/Next, or Gulp
- **⚡ Fast Setup**: Automated installation and configuration
- **📦 Pre-configured Structure**: Industry-standard project organization
- **🔄 Git Integration**: Automatic repository initialization with proper .gitignore
- **💼 Solution File**: Visual Studio solution file created automatically
- **🎯 Template System**: Pre-built templates for components and modules

## 📖 Getting Started

### Prerequisites

Before starting, ensure you have:

- **Node.js** (v14 or higher)
- **npm** or **yarn** package manager
- **.NET SDK** (will be installed automatically if not present)

### Installation & Setup

After the initial setup is complete, follow these steps to get your Umbraco project running:

#### 1. Run the Umbraco Project

Navigate to your project directory and start the application:

```bash
cd YourProjectName
dotnet run
```

Or specify the project explicitly:

```bash
dotnet run --project YourProjectName
```

The application will start and the accessible URL will be displayed in the terminal/console.

#### 2. Complete Umbraco Installation

On the first run, complete the Umbraco installation wizard:

1. **Open your browser** and navigate to the URL displayed in the terminal
2. **Follow the setup wizard**:
   - Select your database provider (SQL Server, SQLite, etc.)
   - Configure database connection
   - Create your admin account (username, email, and password)
   - Configure basic settings
3. **Complete setup** and log in to the Umbraco backoffice at `/umbraco`

#### 3. Start Developing

Your project is now ready for development:

- **Frontend Development**:
  - For **Gulp**: Run `gulp` in the frontend directory
  - For **React/Next**: Run `npm run dev` in the frontend directory
  - For **Vue/Nuxt**: Run `npm run dev` in the frontend directory
- **Umbraco Backoffice**: Access at `https://localhost:XXXX/umbraco` to manage content
- **Template Customization**: Edit Razor views in the `Views/` folder

### Development Workflow

```bash
# Terminal 1: Run Umbraco backend
cd YourProjectName
dotnet run

# Terminal 2: Run frontend build process (in another terminal)
cd YourProjectName/Frontend
npm run dev  # or gulp watch for Gulp projects
```

## 📁 Project Structure

After running the tool, your Umbraco project will have the following structure:

### Root Level

```
YourProjectName/
├── 📄 YourProjectName.sln          # Visual Studio solution file
├── 📁 YourProjectName/             # Main Umbraco project
│   ├── 📁 Frontend/                # Frontend code (Gulp/React/Vue)
│   ├── 📁 Views/                   # Umbraco Razor views
│   ├── 📁 wwwroot/                 # Static files (CSS, JS, images)
│   ├── ⚙️ appsettings.json         # Umbraco configuration
│   └── 📄 Program.cs               # Application entry point
├── 📄 package.json                 # Frontend dependencies
└── 📄 .gitignore                   # Git ignore rules
```

### Frontend Directory Structure

The structure of the `Frontend/` directory varies depending on your chosen technology:

<details>
<summary><b>🔧 Gulp Structure</b></summary>

```
Frontend/
├── 📄 gulpfile.js                  # Gulp task configuration
├── 📄 main.js                      # Main JavaScript entry point
├── 📁 components/                  # Reusable UI components
│   └── componentA/
│       ├── componentA.js
│       └── componentA.scss
├── 📁 modules/                     # Feature modules
│   └── moduleA/
│       ├── moduleA.js
│       └── moduleA.scss
├── 📁 scss/                        # Sass stylesheets
│   ├── main.scss
│   └── core/
│       ├── _colors.scss
│       ├── _reset.scss
│       ├── _skeleton.scss
│       ├── _typography.scss
│       └── _variables.scss
├── 📁 tasks/                       # Custom Gulp tasks
└── 📁 utils/
    └── utils.js                    # JavaScript utilities
```

**Gulp Commands:**

- `gulp` - Build frontend assets
- `gulp watch` - Watch for changes and rebuild automatically
- `gulp build` - Production build with minification

</details>

<details>
<summary><b>⚛️ React/Next.js Structure</b></summary>

```
Frontend/
├── 📄 package.json
├── 📄 next.config.js              # Next.js configuration (if using Next)
├── 📁 src/
│   ├── 📁 components/              # React components
│   ├── 📁 pages/                   # Next.js pages (if using Next.js)
│   ├── 📁 styles/                  # CSS/SCSS files
│   └── 📁 utils/                   # Utility functions
└── 📁 public/                      # Static assets
```

**React Commands:**

- `npm run dev` - Start development server
- `npm run build` - Create production build
- `npm start` - Start production server

</details>

<details>
<summary><b>🎨 Vue/Nuxt.js Structure</b></summary>

```
Frontend/
├── 📄 package.json
├── 📄 nuxt.config.js              # Nuxt.js configuration (if using Nuxt)
├── 📁 src/
│   ├── 📁 components/              # Vue components
│   ├── 📁 pages/                   # Nuxt.js pages (if using Nuxt.js)
│   ├── 📁 assets/                  # CSS/SCSS files
│   └── 📁 composables/             # Vue composables
└── 📁 public/                      # Static assets
```

**Vue Commands:**

- `npm run dev` - Start development server
- `npm run build` - Create production build
- `npm run preview` - Preview production build

</details>

### Umbraco Views Structure

The Umbraco template structure for rendering content:

```
Views/
├── 📁 Partials/
│   ├── 📁 Renderization/
│   │   └── Render_Modules.cshtml         # Helper for rendering modules
│   ├── 📁 WebsiteBase/                   # Base website templates
│   └── 📁 WebsiteContent/
│       ├── 📁 Components/                 # Umbraco component views
│       └── 📁 Modules/
│           └── Content/
│               └── ModuleA/
│                   └── Render_ModuleA.cshtml
└── [Your custom views]
```

### Key Directories Explained

| Directory                          | Purpose                                                                         |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| **Frontend/**                      | All frontend code (JavaScript, CSS, components). Build outputs go to `wwwroot/` |
| **Views/**                         | Umbraco Razor templates for rendering content from the CMS                      |
| **wwwroot/**                       | Static files served directly by the web server (compiled CSS/JS, images, fonts) |
| **Views/Partials/WebsiteContent/** | Organize your Umbraco components and modules here                               |

## 🛠️ Technology Stack

### Backend

- **Umbraco CMS** - Modern .NET CMS platform
- **.NET SDK** - Cross-platform .NET runtime
- **C#** - Primary backend language

### Frontend Options

- **Vue.js / Nuxt.js** - Progressive JavaScript framework
- **React / Next.js** - Popular component-based library
- **Gulp** - Task runner for build automation

### Additional Tools

- **Git** - Version control
- **TypeScript** - Type-safe JavaScript (optional)
- **Sass/SCSS** - CSS preprocessor

## 💡 Best Practices

### Recommended Workflow

1. **Start with Umbraco**: Set up your content types and document structure first
2. **Create Templates**: Build Razor views for your content types
3. **Develop Frontend**: Build components and styles for your templates
4. **Test Locally**: Always test changes before deployment
5. **Use Version Control**: Commit frequently with descriptive messages

### Tips

- 💾 **Backup regularly**: Especially before major updates
- 📝 **Document your content types**: Keep documentation for custom properties
- 🎯 **Use partial views**: Create reusable Razor components
- ⚡ **Optimize assets**: Minify CSS/JS for production
- 🔒 **Secure your installation**: Follow Umbraco security best practices

## ⚠️ Important Notes

### Git Repository

⚠️ **Important**: When adding Init-Spark Umbraco to an existing Git repository, it is recommended to use an empty repository to avoid conflicts with existing files.

### Database Configuration

On first run, you'll need to configure your database. For development:

- **SQLite**: Simplest option, no additional setup required (automatically configured if using automatic installation)
- **SQL Server**: Requires SQL Server installation (only available with manual database configuration)
- **MySQL/PostgreSQL**: Requires additional provider installation (only available with manual database configuration)

**Note**: If you chose automatic installation during setup, SQLite will be pre-configured. Manual database configuration is only required if you opted out of automatic setup.

## 📝 License

This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for full details.

### What this means

- ✅ Commercial use allowed
- ✅ Modification allowed
- ✅ Distribution allowed
- ✅ Private use allowed

## 💖 Support the Project

If you find this tool helpful, consider supporting its development:

[![Donate with PayPal](https://img.shields.io/badge/Donate-PayPal-blue.svg)](https://www.paypal.com/donate/?hosted_button_id=NXDY66SK4REGY)

Your support helps maintain and improve the tool for everyone!

## 📚 Additional Resources

- [Umbraco Documentation](https://docs.umbraco.com/)
- [.NET Documentation](https://docs.microsoft.com/dotnet/)
- [Vue.js Guide](https://vuejs.org/guide/)
- [React Documentation](https://react.dev/)
- [Gulp Documentation](https://gulpjs.com/)

## 👤 Author

**João Borges**