🎭 Trickster

A modern, battle-tested micro-framework for building web applications in Perl.

Documentation • Quick Start • Examples • Contributing

Philosophy

Trickster brings contemporary web framework design to Perl while respecting CPAN traditions.

• Minimal Core – Light dependencies, focused on essentials
• PSGI Native – Built on PSGI/Plack for maximum compatibility
• Modern Perl – Uses Perl 5.14+ features while remaining accessible
• CPAN Friendly – Integrates seamlessly with existing CPAN modules
• Battle-Tested – Production-grade error handling and performance
• No Magic – Explicit is better than implicit

Installation

Via CPAN

cpanm Trickster

Via cpanfile

cpanm --installdeps .

Traditional CPAN

perl Makefile.PL
make
make test
make install

This will also install the trickster command-line tool.

Quick Start

Using the CLI (Recommended)

# Create a new application
trickster new myapp

# Navigate and install dependencies
cd myapp && cpanm --installdeps .

# Start the development server
trickster server

Visit http://localhost:5678

Hello World (Manual)

use Trickster;

my $app = Trickster->new;

$app->get('/', sub {
    my ($req, $res) = @_;
    return "Welcome to Trickster";
});

$app->get('/hello/:name', sub {
    my ($req, $res) = @_;
    my $name = $req->param('name');
    return "Hello, $name";
});

$app->to_app;

Run with any PSGI server:

plackup app.psgi

Features

Code Examples

REST API with JSON

use Trickster;
use Trickster::Request;
use Trickster::Response;

my $app = Trickster->new;

$app->get('/api/users/:id', sub {
    my ($req, $res) = @_;
    $req = Trickster::Request->new($req->env);
    $res = Trickster::Response->new;
    
    my $id = $req->param('id');
    my $user = get_user($id);
    
    return $res->json($user);
});

$app->post('/api/users', sub {
    my ($req, $res) = @_;
    $req = Trickster::Request->new($req->env);
    $res = Trickster::Response->new;
    
    my $data = $req->json;
    my $user = create_user($data);
    
    return $res->json($user, 201);
});

Data Validation

use Trickster::Validator;

$app->post('/register', sub {
    my ($req, $res) = @_;
    my $data = $req->json;
    
    my $validator = Trickster::Validator->new({
        name  => ['required', ['min', 3], ['max', 50]],
        email => ['required', 'email'],
        age   => ['numeric', ['min', 18]],
    });
    
    unless ($validator->validate($data)) {
        return $res->json({ errors => $validator->errors }, 400);
    }
    
    # Process valid data...
    return $res->json({ success => 1 }, 201);
});

Template Rendering

use Trickster::Template;

my $template = Trickster::Template->new(
    path => ['templates'],
    cache => 1,
    layout => 'layouts/main.tx',
);

$app->get('/profile/:username', sub {
    my ($req, $res) = @_;
    my $username = $req->param('username');
    
    my $html = $template->render('profile.tx', {
        title => 'User Profile',
        user  => get_user($username),
    });
    
    return $res->html($html);
});

Exception Handling

use Trickster::Exception;

$app->get('/user/:id', sub {
    my ($req, $res) = @_;
    my $id = $req->param('id');
    
    my $user = find_user($id);
    
    unless ($user) {
        Trickster::Exception::NotFound->throw(
            message => "User not found"
        );
    }
    
    return $res->json($user);
});

# Custom error handler
$app->error_handler(sub {
    my ($error, $req, $res) = @_;
    
    if (ref($error) && $error->isa('Trickster::Exception')) {
        return $res->json($error->as_hash, $error->status)->finalize;
    }
    
    return $res->json({ error => 'Server Error' }, 500)->finalize;
});

CLI Commands

Trickster includes a powerful command-line interface:

# Scaffold new application
trickster new myapp

# Generate components
trickster generate controller User
trickster generate model Post
trickster generate template about

# Development server with hot-reload
trickster server --reload --port 3000

# Show version
trickster version

Testing

Comprehensive test suite included:

# Run all tests
prove -l t/

# With verbose output
prove -lv t/

# Single test file
prove -lv t/01-routing.t

Test coverage: 85%+

Documentation

• Getting Started Guide – Learn the basics
• API Reference – Complete API docs
• Cookbook – Common recipes
• Examples – Working code examples
• Migration Guide – From other frameworks

Examples

Check out the examples/ directory for complete working applications:

| Example | Description | Run Command | |---------|-------------|-------------| | hello.psgi | Basic routing & parameters | plackup examples/hello.psgi | | api.psgi | Full REST API with CRUD | plackup examples/api.psgi | | template.psgi | Template engine demo | plackup examples/template.psgi | | advanced.psgi | All features showcase | plackup examples/advanced.psgi | | middleware.psgi | Middleware integration | plackup examples/middleware.psgi |

Requirements

Core Dependencies

• Perl 5.14+
• Plack 1.0047+
• JSON::PP (core)
• URI::Escape (core)
• Digest::SHA (core)
• Time::Piece (core)

Optional

• Text::Xslate 3.0+ – For template engine support

cpanm Text::Xslate
# or
cpanm --installdeps . --with-feature=templates

Contributing

Contributions are welcome. Please ensure:

• Code follows Perl best practices
• Tests are included for new features
• Documentation is updated
• Changes maintain backward compatibility

See CONTRIBUTING.md for details.

License

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, under the terms of either:

• The Artistic License 2.0
• The GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version

See LICENSE for more details.

Author

Trickster Contributors