# Lux Package System

Lux includes a built-in package manager for managing dependencies.

## Quick Start

### Initialize a Project

```bash
# Create a new project directory
lux init my-project
cd my-project

# Or initialize in an existing directory
lux pkg init
lux pkg init my-project-name
```

This creates a `lux.toml` manifest file:

```toml
[project]
name = "my-project"
version = "0.1.0"
description = "A Lux project"

[dependencies]
# Add dependencies here
```

### Adding Dependencies

```bash
# From a git repository
lux pkg add mylib --git https://github.com/user/mylib

# From a local path
lux pkg add local-lib --path ../lib

# With a specific version (for future registry support)
lux pkg add http 1.0.0
```

### Installing Dependencies

```bash
lux pkg install
```

This installs all dependencies listed in `lux.toml` to the `.lux_packages/` directory.

### Using Packages

Once installed, import packages in your Lux code:

```lux
import mylib

let result = mylib.doSomething()
```

## Commands Reference

| Command | Description |
|---------|-------------|
| `lux pkg init [name]` | Initialize a lux.toml in the current directory |
| `lux pkg install` | Install all dependencies from lux.toml |
| `lux pkg add <pkg>` | Add a dependency |
| `lux pkg remove <pkg>` | Remove a dependency |
| `lux pkg list` | List dependencies and their status |
| `lux pkg update` | Update all dependencies |
| `lux pkg clean` | Remove installed packages |

## Dependency Sources

### Git Repository

```toml
[dependencies]
mylib = { git = "https://github.com/user/mylib" }
mylib = { git = "https://github.com/user/mylib", branch = "main" }
```

### Local Path

```toml
[dependencies]
local-lib = { path = "../local-lib" }
```

### Registry (Future)

```toml
[dependencies]
http = "1.0.0"
```

## Package Structure

A valid Lux package must have one of these entry points:

1. `lib.lux` - Main module file in package root
2. `src/lib.lux` - Main module file in src directory

Example package structure:

```
mypackage/
├── lux.toml
├── lib.lux          # Entry point (option 1)
└── src/
    └── lib.lux      # Entry point (option 2)
```

The entry point should export public functions:

```lux
// lib.lux
pub fn helper(x: Int): Int = x * 2

pub fn process(data: String): String = {
    // Implementation
    data
}
```

## Project Layout

A typical Lux project looks like:

```
my-project/
├── lux.toml           # Project manifest
├── src/
│   └── main.lux       # Main source file
├── tests/
│   └── test.lux       # Test files
└── .lux_packages/     # Installed dependencies (gitignore this)
    ├── mylib/
    │   └── lib.lux
    └── utils/
        └── lib.lux
```

## Standard Library

The Lux standard library is available as a package:

```bash
lux pkg add stdlib --path /path/to/lux/stdlib
```

Or use the built-in modules directly:

```lux
// Built-in modules (always available)
import html       // Type-safe HTML construction
import browser    // Browser effects (Dom, Storage, Navigation)
```

## Best Practices

1. **Add `.lux_packages/` to `.gitignore`** - Dependencies should be installed, not committed

2. **Use semantic versioning** - When publishing packages, follow semver

3. **Document your exports** - Add comments to public functions

4. **Keep packages focused** - One package should do one thing well

## Future Features

- **Package Registry** - Central repository for sharing packages
- **Version Resolution** - Automatic dependency version management
- **Lock File** - Reproducible builds with exact versions
- **Publishing** - `lux pkg publish` command