DOCSEARCHbyAlgolia
Submit Docs

Lucky Framework

website·Indexed 30 days ago

https://luckyframework.fly.dev/guides/getting-started/installing

A web framework for the Crystal programming language. The documentation covers core features including HTTP routing, JSON API development, database operations, authentication, asset handling with Bun, and deployment to platforms like Dokku. It includes guides on testing actions, security headers, and internationalization, with version support up to v1.5.0.

Tokens
76.2K
Snippets
539
Records
611
Agent score
57%

What's inside Lucky

  1. Overview of the Lucky framework philosophy

    Lucky is a web framework designed to prioritize reliability and developer productivity by leveraging the Crystal language's type system. Its core goals include catching bugs at compile time rather than in production, minimizing boilerplate code, and using conventions to reduce guesswork. This approach allows developers to spend less time writing tests and debugging, as the compiler validates many common failure points.

  2. Overview of the Lucky Framework Ecosystem

    The Lucky framework consists of a modular ecosystem of 'shards' and libraries that provide core web development functionality. Key components include:

    • Lucky: The main framework shard.
    • Lucky Cli: Command-line interface for generating new Lucky applications.
    • Avram: The framework's ORM.
    • Authentic: User authentication system integrated with Avram.
    • Carbon: Email creation and delivery system with multiple adapter support.
    • Habitat: Utility to make any object configurable.
    • Breeze: A development dashboard.
    • Dexter: A logging utility and formatter.
    • LuckyTask: Library for creating command-line tasks.
    • Wordsmith: Handles word pluralization and ordinalizing.
    • Pulsar: Event publishing and subscription system (Pub/Sub).
    • Lucky Router: Handles HTTP path routing.
    • Lucky Flow: Tool for automated browser control and testing.
    • Lucky Env: Environment variable parser.
    • Lucky Cache: Content caching for Lucky applications.
    • LuckySecTester: Integrated security specifications using BrightSec.
    • LuckyTemplate: Utility for templatizing files and folders.
    • LuckyHXML: Hyperview implementation similar to LuckyHTML.

  3. Overview of LuckyFlow for browser testing

    LuckyFlow is a shard used to programmatically control a browser to test front-end interactivity and user flows (e.g., a sequence of actions from login to dashboard). It is automatically installed and configured in Lucky 'full' or 'web' projects. It uses chromedriver and Selenium under the hood, automatically installing the driver on the first run.

  4. Overview of metadata extraction in Latch

    Metadata extraction in Latch uses 'extractors'—small structs that read an uploaded file and write values into the StoredFile metadata object. This metadata is persisted in the database as JSON, allowing developers to access file properties (like size or dimensions) without querying the storage backend.

  5. Overview of Lucky authentication generated files

    When lucky init is run with authentication enabled, the framework generates a set of boilerplate files. API-only apps receive token-based (JWT) auth, while full apps receive both API and browser-based (cookie) auth.

  6. Overview of the Lucky web framework

    Lucky is a high-performance web framework written in Crystal designed to catch bugs at compile time and deliver fast responses. It follows a 'batteries included' philosophy, providing built-in support for authentication, asset management, CORS, and a database ORM.

  7. Overview of Avram ORM in Lucky

    Avram is the default Object Relational Mapping (ORM) tool used by the Lucky framework to map SQL database tables to Crystal classes. It currently only supports PostgreSQL. Avram separates business logic from database queries by utilizing a specific set of class types: Models, Queries, Operations, Migrations, and Factories.

  8. Overview of file uploads with Latch in Lucky

    Lucky uses the Latch library for file attachments. A complete file upload implementation consists of three main components:

    1. Uploader: Defines how a file is stored, what metadata is extracted, and how it is processed.
    2. Storage Backend: Handles the physical persistence of the file (e.g., local disk, S3, or in-memory for testing).
    3. Avram Integration: Connects the file attachment to a model column using macros, managing caching, promotion, replacement, and cleanup.

  9. Overview of new Lucky ecosystem shards

    Lucky v1.1.0 introduces several new shards to expand framework capabilities and cross-platform support:

    • LuckyTemplate: Used for generating project templates; replaces the deprecated Teeplate shard and improves Windows compatibility.
    • LuckyHXML: Allows generation of backend code for Hyperview mobile applications with type-safe, compile-time catches.
    • LuckyHTMX: An unofficial community shard for easier integration with the HTMX library.

  10. Implement Internationalization with Rosetta in Lucky

    Lucky uses the Rosetta shard for internationalization because it handles key lookup at compile-time and integrates deeply with the framework. Translations can be applied using the r("translation.key").t syntax. To use a specific locale for a block of code, use Rosetta.with_locale(locale) do ... end.
    # Basic translation
r("translation.key.values").t

# Translation with a specific locale
Rosetta.with_locale(current_user.language) do
  r("translation.key.values").t
end

  11. Understand HTML generation in Lucky

    Lucky generates HTML using Crystal classes and methods rather than traditional templates. This approach provides several developer advantages:

    • Type Safety: Prevents unmatched closing tags and ensures pages are not rendered with missing data.
    • Security: Text is automatically escaped to prevent XSS.
    • Maintainability: Partials are extracted and shared using standard Crystal methods, and the entire page structure can be understood by reviewing the render method.
    • Reliability: Eliminates the risk of accidentally printing nil values to the page.

  12. Install Latch in a Lucky application

    To add Latch to your project, add the dependency to shard.yml and run shards install. Depending on your application architecture, you must require different integration files in src/shards.cr to load the correct framework hooks.
    # shard.yml
dependencies:
  latch:
    github: wout/latch

    src/shards.cr

    require "latch"

    Choose ONE of the following based on your needs:

    require "latch/lucky/avram" # For Lucky + Avram (Default) require "latch/lucky/uploaded_file" # For Lucky without Avram (e.g., API-only streaming to S3) require "latch/avram/model" # For Avram used outside of Lucky