lux/docs/PACKAGES.md

Lux Package System

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

Quick Start

Initialize a Project

# 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:

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

[dependencies]
# Add dependencies here

Adding Dependencies

# 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

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:

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

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

Local Path

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

Registry (Future)

[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:

// 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:

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

Or use the built-in modules directly:

// 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