Luma Begins a New Chapter: Introducing Modules & Imports

Today marks one of the most important steps in Luma’s evolution - we’re officially beginning work on Modules & Imports, a feature that will open the door to larger applications, cleaner code organization, reusable libraries, and a more natural way to structure Luma projects.

Until now, Luma has thrived as a simple, expressive language for small scripts, utilities, experiments, and learning. But every growing language eventually reaches a point where code needs to be split across multiple files. That moment has arrived - and we’re excited to share what’s coming next.

Why Modules Matter

As soon as projects expand beyond a single file, developers want to:

• separate functionality into logical pieces
• keep related code together
• avoid enormous “everything in one place” source files
• reuse the same helper code across different scripts
• build small libraries that others can import

Modules are the foundation that make all of this possible.

With modules, every .luma file becomes a self-contained unit, and you choose which file becomes the “entrypoint” of your program. This keeps Luma as simple as ever - but now scales to bigger ideas.

A Clear and Friendly Design

One of our goals has always been keeping Luma predictable and easy to understand. So instead of adding complex concepts like package manifests, folder-level configuration, or mandatory project layouts, we’re sticking to something extremely simple:

You run one Luma file - that file is your application.
Anything it imports becomes part of the program.

That’s it.

This means:

• You can run any file directly: luma run app.luma luma run tools/backup.luma luma run scripts/demo.luma
• Each file can import other files.
• Only the files you import are included.
• And your project can be organized however you prefer - no rules forced on you.

Just like the rest of Luma, the module system stays out of your way until you need it.

Building Reusable Code

Modules also give us something new: a way to share functionality cleanly.

You’ll be able to mark functions as public:

pub fn greet(name: str) -> str {
    return "Hello, ${name}!"
}

And then import them from another file:

g = import "greetings"
print(g.greet("Luma"))

The idea is to keep things clear and explicit: you decide what your module exposes, and you decide what you want to import.

No hidden behavior, no magic.
Exactly what Luma promises.

No Circular Headaches

One of the easiest ways for a module system to become confusing is to allow circular imports, where two files depend on each other. This usually leads to complex initialization rules and mysterious bugs.

So we’ve made a simple decision:

Circular imports won’t be allowed.

If file A depends on B, and B depends on A, Luma will tell you clearly so you can reorganize the code - often by moving shared logic into a third module. This choice keeps the language predictable and avoids surprising behavior.

A Natural Step Toward Larger Applications

Modules bring us closer to features that many people have been asking for:

• first-class libraries
• reusable utility files
• shared domain models
• user-built toolkits
• long-running programs like servers
• better structure for bigger apps
• clearer separation of concerns

And the best part?
You don’t have to learn a massive system to get there.
If you already know Luma, modules will feel completely natural.

Keeping the Spirit of Luma

Even as Luma grows, we stay true to our core principles:

• Simplicity over complexity
• Predictable behavior
• Clear syntax
• Minimal boilerplate
• A language you can understand at a glance

Modules are not being added to complicate Luma - they’re being added to let your ideas grow.

What’s Next?

The implementation work begins now.
Over the coming weeks you can expect:

• early experimental support for import
• draft documentation on module behavior
• discussions on naming, visibility, and structure
• first working versions in the compiler
• examples and tutorials

We’ll share progress as it happens, and your feedback will shape the design as much as our own ideas.

Thank You

Luma is still young, but the excitement and curiosity from the community is exactly what keeps it moving forward. Modules & Imports will unlock whole new layers of possibility, and we can’t wait to build them together with you.

Stay tuned - big things are coming.