Skip to content

ProjectStructure.md

Latest commit

聽

History

History
95 lines (61 loc) 路 5.29 KB

ProjectStructure.md

File metadata and controls

95 lines (61 loc) 路 5.29 KB
Raw

Klar Project Structure

This document describes the structure of projects and special files and directories for Klar implementations.

Note: This document describes the layout of projects compiled by Klar, not the Klar compiler itself.

Project Directories/Root Folders

For full Klar projects with a glas.pack, these folders inside the same folder as glas.pack should be detected. Any other folder is ignored by the Klar toolchain. Modules are found in these folders.

Name Contains Public Downloaded
cmd Installable and runnable commands. Even if your project is private, it is recommended to place your commands in this folder. Yes Yes
dist Build output. This should be included in .gitignore. No No
docs Markdown files that can be included in package documentation. No Yes
external Files written in other languages for linking in @external. Available to all packages. No Yes
generated Generated files, usually Klar scripts or external scripts. Files here should not be manually edited. No Yes
pkg Packages in a single project/monorepo Yes Installed individually
recipes Klar recipes (coming soon). Individual Klar scripts are placed here. No No
scripts Individual Klar scripts not inside modules. Used for development. No No
shared Modules available to all packages in a project, but not outside. No Yes
src Entry files for a package. Most files and modules should be here. Yes Yes
.klar Project-specific folder for project data, cache, and dependencies as an alternative to installing them globally on the machine. This should be included in .gitignore. No No

Projectless Scripts

Klar scripts placed outside a project with a glas.pack file are allowed.

  • Are discrete modules, even with files in the same folder
  • Must be run by name
  • Cannot install or import modules outside the standard library

Manifest/Configuration Files

glas.pack

The glas.pack defines a project or package. It is only allowed in the project root and/or a package. If it is found in both, the glas.lock in the package will merge with, but override, the glas.pack in the project.

klar.build

klar.build is Klar's build configuration file. It is akin to vite.config.js or webpack.config.js. The klar.build file defines default build options when compiling a project, package, or module. It is allowed in the project root, the pkg directory, any package root, or any module inside. When compiling, the closest klar.build file to the input is used.

glas.lock

The lockfile for the Glas package manager. The glas.lock file stores the list of packages and versions to install when installing dependencies for a project. A glas.lock file must always be paired with a glas.pack file.

klardoc.json

Prebuilt documentation for a project, containing the index of a package's exports and all documentation and type definitions. The klardoc.json file is stored only in the project root. This file is autogenerated and should not be manually edited.

Modules

Modules are defined by directories. Creating a directory inside a directory creates a submodule. Modules can be imported into Klar scripts by their path. Klar import paths are separated by dot characters (.)

Module Identifiers

The module identifier is the name of the directory. A module identifier:

  • can contain any Unicode letter or digit or underscores (_)
  • cannot be a keyword (such as import, func, or go) or a modifier (public, opaque, etc.)
  • cannot be a special project directory (such as pkg)
  • cannot begin with a digit
  • cannot be only a single underscore (_)

Most valid Klar identifiers are valid module identifiers. If an identifier is not a valid Klar identifier, it is not a valid module identifier.

The top-level module may not be named klar.

Allowed: a, b6, core, HOLA, caf茅 Not allowed: import, go, public, cmd, 67, 3dlib, _

Important

Validation of directory names is not required. It is recommended that users avoid module names that are OS-reserved, such as con on Windows.

Path Limits

No more than four (4) folders/parts in a module. This starts from the folder inside src.
Allowed: a.b.c.d (4 parts)
Not allowed: a.b.c.d.e (5 parts)

Installing Modules

Files included in a downloaded module: glas.pack, glas.lock, klardoc.json

Assets

Scripts: .klar, .js, .ts, .wasm, .php
Stylesheets: .css, .scss, .sass, .less Media: .png, .jpeg, .jpg, .svg, .webp, .gif, .mp4, .mp3, .wav, .webm, .tiff
Markup: .xml, .json, .html, .klon, .txt, .csv, .tsv
Fonts: .ttf, .otf, .woff, .woff2