shelf_serve 0.2.7

shelf_serve #

Configure and run a http server.

Defining a http server #

You define a http server by creating a shelf_serve.yaml file. This file lists the middleware and handlers that should be used to handle requests. For example:

    type: compound
        type: pub
          path: test_web
        type: static
        path: test_static
    type: proxy
    type: rpc
    type: echo


    path: test_api
    path: test_echo

Adding middleware #

In the middlewares section of the shelf_serve.yaml file, you can list the middlewares to be used and define optional configuration parameters.

There are two build in middlewares:

  • log_requests logs requests to stdout.
  • cors adds cors headers to the response.


      headers: "rpc-auth, content-type"
      methods: "POST, GET, PUT, OPTIONS, DELETE"
      origin: "*"

Adding handlers #

In the handlers section of the shelf_serve.yaml file, you can list different handlers to be used for different routes.

There are five build in handlers:

  • static serves the static files in the directory defined by the path parameter.
  • pub runs pub serve on a dart package and forwards requests to it.
  • proxy proxies requests to the server defined in the url parameter.
  • rpc serves a rest api defined by the rpc package.
  • compound a compound handler that can contain other handlers and middlewares.

Note: when using the rpc handler, you should add the package that defines the api classes in the dependencies section.

Defining custom handlers and middleware #

You can define custom handlers and middleware by annotating a factory function that creates the handler or middleware based on some configuration parameters.

For example

import 'package:shelf_serve/shelf_serve.dart';
import 'package:shelf/shelf.dart';

createEchoHandler(String type, String route,
                      Map<String,dynamic> config) {
  return (Request r) async => new Response.ok(await r.readAsString());

You should add the package that defines those custom handlers and middlewares to the dependencies section.

Running the server from command line #

First install the shelf_serve executable:

pub global activate shelf_serve

Then goto the directory where the shelf_serve.yaml file is located and run:

shelf_serve serve

By default the server will listen to port 8080. You can define another port by:

shelf_serve serve --port 5000

Running the server from code #

Create a dart file and import all the necessary dependencies.

Run the method serve:

serve('path/to/shelf_serve.yaml', port: 5000);

Alternatively, you can run the method serveInIsolate, which will automatically do all the necessary imports based on the dependencies section in the shelf_serve.yaml file.

Creating a docker file #

First install the shelf_serve executable:

pub global activate shelf_serve

Then goto the directory where the shelf_serve.yaml file is located and run:

shelf_serve create-docker-project

By default the project will be created in build/project. To select another output directory run:

shelf_serve create-docker-project --output-directory some/other/path

Next, go to the built project directory. There will be a Dockerfile there. You can create a container image by running:

docker build -t my/app .

And to run this image:

docker run -d -p 8080:8080 my/app

Changelog #

0.2.7 #

  • add gzip middleware

0.2.0 #

  • api changes
  • create docker project

0.1.0 #

  • api changes
  • command line utility

0.0.1 #

  • Initial version

Use this package as an executable

1. Install it

You can install the package from the command line:

$ pub global activate shelf_serve

2. Use it

The package has the following executables:

$ shelf_serve

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  shelf_serve: ^0.2.7

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:shelf_serve/shelf_serve.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

The package version is not analyzed, because it does not support Dart 2. Until this is resolved, the package will receive a health and maintenance score of 0.

Analysis issues and suggestions

Support Dart 2 in pubspec.yaml.

The SDK constraint in pubspec.yaml doesn't allow the Dart 2.0.0 release. For information about upgrading it to be Dart 2 compatible, please see

Maintenance issues and suggestions

Make sure dartdoc successfully runs on your package's source files. (-10 points)

Dependencies were not resolved.