Deno Cloud Native Buildpack

A Cloud Native Buildpack for Deno applications that automatically detects and builds Deno projects with proper dependency caching and multi-architecture support.

Features

• 🚀 Automatic Detection: Detects Deno applications based on configuration files and TypeScript entry points
• 📦 Smart Caching: Three-layer caching system for runtime, dependencies, and application code
• 🏗️ Multi-Architecture: Supports both AMD64 and ARM64 architectures
• 🔧 Version Management: Supports .deno-version files and external version configuration
• 🌐 Network Resilience: Robust download handling with retry logic and comprehensive error messages
• ⚡ Fast Rebuilds: Efficient layer invalidation and restoration for quick subsequent builds

Quick Start

Prerequisites

• Docker installed
• Pack CLI installed

Building Your Deno Application

# Build your Deno app using this buildpack
pack build my-deno-app --buildpack julianduque/deno-cnb

# Run the built image
docker run --rm -p 8080:8080 my-deno-app

Supported Project Structures

The buildpack automatically detects Deno applications that have any of the following:

• deno.json or deno.jsonc configuration files
• TypeScript entry points: main.ts, mod.ts, app.ts, or index.ts
• deno.lock lock file
• .deno-version version specification file

Example Project Structure

my-deno-app/
├── deno.json          # Deno configuration
├── .deno-version      # Optional: specify Deno version
├── main.ts            # Application entry point
└── deps.ts            # Optional: dependency management

Configuration

Deno Version Management

The buildpack supports multiple ways to specify the Deno version:

1. .deno-version file (recommended):

   2.3.1
   

2. Default version: Falls back to the latest stable version defined in the buildpack's inventory

Application Entry Point

Your Deno application should define a start task in deno.json:

{
  "tasks": {
    "start": "deno run --allow-net --allow-read main.ts"
  }
}

The buildpack will execute deno run start to launch your application.

Layer Architecture

The buildpack uses a three-layer caching strategy:

1. Runtime Layer (deno-runtime): Contains the Deno binary

   • Cached based on Deno version and architecture
   • Shared across builds with the same Deno version

2. Dependencies Layer (deno-dependencies): Contains cached dependencies

   • Invalidated when deno.lock or deno.json/deno.jsonc changes
   • Significantly speeds up builds with unchanged dependencies

3. Application Layer (deno-app): Contains your application code

   • Rebuilt on every build to capture code changes
   • Lightweight since dependencies are cached separately

Development

Building the Buildpack

# Package the buildpack
cargo libcnb package

# The packaged buildpack will be available in the packaged/ directory

Testing

The project includes comprehensive test fixtures:

# Run all tests
cd test-fixtures
./run-tests.sh

# Test specific fixture
./run-tests.sh basic-web-server

Test Fixtures

• basic-web-server: Simple HTTP server using native Deno APIs
• with-dependencies: Tests external dependency resolution
• complex-config: Complex deno.jsonc configuration
• with-version-file: Tests .deno-version file handling
• minimal-app: Bare minimum setup

Architecture Support

• AMD64 (x86_64): Fully supported
• ARM64 (aarch64): Fully supported

The buildpack automatically detects the target architecture and downloads the appropriate Deno binary.

Error Handling

The buildpack provides comprehensive error messages and troubleshooting guidance for common issues:

• Network connectivity problems
• Invalid Deno versions
• Missing or corrupted downloads
• Configuration file issues
• Dependency resolution failures

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

Development Setup

# Clone the repository
git clone https://github.com/julianduque/deno-cnb.git
cd deno-cnb

# Build the buildpack
cargo libcnb package

# Run tests
cd test-fixtures
./run-tests.sh

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Deno - The secure runtime for JavaScript and TypeScript
• Cloud Native Buildpacks - The specification and ecosystem
• libcnb.rs - The Rust framework for buildpacks

Support

• 📚 Deno Documentation
• 🏗️ Cloud Native Buildpacks Documentation
• 🐛 Report Issues

---

Built with 💜 for the Heroku, Deno and Cloud Native communities.