pack.gl

pack.gl

Package Pipeline Manager

---

Package Builder for the .gl-libraries of Scape Agency and its affiliates.

Pack.gl is a highly customizable and efficient package builder designed to streamline software development workflows. It provides a modular framework for managing build pipelines with support for live reload functionality.

pack.gl is a package builder designed to enhance the efficiency and organization of software development projects. Key to its design philosophy is the adaptability to various development workflows, making it an ideal companion for a range of projects from small-scale personal endeavors to large, complex enterprise applications. pack.gl stands not just as a tool but as a partner in the software development journey, enhancing productivity, reducing overhead, and bringing clarity and ease to the package management process.

---

Features

• Modular pipeline system with stages and steps.
• Live reload functionality for enhanced developer experience.
• Plugin-based architecture to extend functionality.
• TypeScript support for a modern development workflow.
• Robust error handling and logging.

---

Quickstart

To install pack.gl, use npm or yarn:

NPM

npm install pack.gl --save-dev

Yarn

yarn add pack.gl --dev

---

Installation

1. Clone the Repository:

   git clone <https://github.com/stylescape/pack.gl.git>
   cd pack.gl
   

2. Install Dependencies:

   npm install
   

3. Build the Project:

   npm run build
   

4. Link the CLI Globally:

   npm link
   

---

Usage

Run the Pipeline

Run the pipeline defined in your pack.yaml file:

pack

Enable Live Reload

Run the pipeline with live reload enabled:

pack --live

---

Configuration

The pipeline configuration is defined in a pack.yaml file located in the root of your project. Here’s an example:

stages:

- name: build
    steps:
  - name: compile
        action: build
        options:
          source: src/
          output: dist/
- name: test
    dependsOn: [build]
    steps:
  - name: run-tests
        action: test

Stage and Step Structure

• Stages: Define a group of steps to be executed.
• Steps: Individual tasks within a stage (e.g., compiling, testing).
• Dependencies: Stages can depend on other stages to enforce execution order.

---

Development

Build

Compile the TypeScript files into JavaScript:

npm run build-tsc

Lint

Run ESLint to check for code issues:

npm run lint

Run Tests

Run all tests in the src/tests directory:

npm run test

Live Reload

To enable live reload during development, add the --live flag:

pack --live

---

Folder Structure

pack.gl/
├── src/
│   ├── core/           # Core pipeline logic
│   ├── live/           # Live reload server and related components
│   ├── actions/        # Built-in step actions (e.g., build, test)
│   ├── tests/          # Unit tests
│   └── pack.ts         # Entry point for the CLI
├── dist/               # Compiled JavaScript output
├── pack.yaml           # Example configuration file
├── package.json        # Project metadata and dependencies
├── tsconfig.json       # TypeScript configuration
└── README.md           # Project documentation

---

Key Components

Pipeline

The Pipeline class manages the execution of stages and steps defined in the pack.yaml file.

LiveReloadServer

The LiveReloadServer provides live reload functionality by watching files for changes and notifying connected clients.

ConfigLoader

The ConfigLoader reads and validates the pipeline configuration from the pack.yaml file.

Actions

Pack.gl supports plugin-based actions. Default actions include:

• build: Compiles source files.
• test: Runs tests.
• lint: Lints the codebase.

Custom actions can be implemented and registered as plugins.

graph TD
    subgraph Pipeline
        Stage1[Stage 1]
        Stage2[Stage 2]
        Stage3[Stage 3]
    end

    subgraph Stage1
        Step1_1[Step 1.1]
        Step1_2[Step 1.2]
    end
    subgraph Stage2
        Step2_1[Step 2.1]
        Step2_2[Step 2.2]
    end
    subgraph Stage3
        Step3_1[Step 3.1]
        Step3_2[Step 3.2]
    end

    Step1_1 --> Action1_1[Action: DirectoryCleanAction]
    Step1_2 --> Action1_2[Action: DirectoryCopyAction]
    Step2_1 --> Action2_1[Action: FileCopyAction]
    Step2_2 --> Action2_2[Action: StyleProcessingAction]
    Step3_1 --> Action3_1[Action: PackageManagerAction]
    Step3_2 --> Action3_2[Action: VersionWriteAction]

    Stage1 --> Stage2
    Stage2 --> Stage3

---

Colophon

Authors

pack.gl is an open-source project by Scape Agency.

Scape Agency

Scape Agency is a spatial innovation collective that dreams, discovers and designs the everyday of tomorrow. We blend design thinking with emerging technologies to create a brighter perspective for people and planet. Our products and services naturalise technology in liveable and sustainable –scapes that spark the imagination and inspire future generations.

• website: scape.agency
• github: github.com/stylescape

Development Resources

Contributing

We'd love for you to contribute and to make this project even better than it is today! Please refer to the contribution guidelines for information.

Contributions are welcome! Follow these steps to contribute:

1. Fork the repository.
2. Create a new feature branch.
3. Make your changes and write tests.
4. Submit a pull request.

Legal Information

Copyright

Copyright © 2024 Scape Agency BV. All Rights Reserved.

License

Except as otherwise noted, the code in this repository is licensed under the MIT License. Also see LICENSE. The documentation is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) License.

Disclaimer

THIS SOFTWARE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.

---

Made with ❤️ by Scape Agency