appengine 0.4.3+1

  • Installing
  • Versions
  • 81

Dart support for Google AppEngine

This package provides support for running server applications written in Dart on Google App Engine using Custom Runtimes with Flex Environment.


Install Dart and Cloud SDKs

This page assumes the Dart SDK (see as well as the Google Cloud SDK (see were installed and their bin folders have been added to PATH.

Setup gcloud

To ensure gcloud was authorized to access the cloud project and we have the app component installed, we assume the following has been run:

$ gcloud auth login
$ gcloud config set project <project-name>
$ gcloud components update app

Creation service account

Furthermore in order to operate on the data of the cloud project, a service account needs to be created which allows downloading a private key in JSON format. Such a key can be obtained via the Cloud Console under IAM & Admin > Service Accounts > Create Service Account.

Creating a hello world application

To setup a hello world application we need 4 different things:

An app/pubspec.yaml file describing the Dart package:

name: hello_world
version: 0.1.0
  appengine: '>=0.4.0 <0.5.0'

An app/app.yaml file describing the AppEngine app:

runtime: custom
env: flex
service: default

An app/Dockerfile describing how to build/bundle the app:

FROM google/dart-runtime

### NOTE: Uncomment the following lines for local testing:
#ADD key.json /project/key.json
#ENV GCLOUD_KEY /project/key.json
#ENV GCLOUD_PROJECT dartlang-pub

An app/bin/server.dart containing the app code

import 'dart:io';
import 'package:appengine/appengine.dart';

requestHandler(HttpRequest request) {
      ..write('Hello, world!')

main() async {
  await runAppEngine(requestHandler);

Running the app locally

There are two ways to run the application locally - with or without docker. Both of which require a service account key.

Running without Docker

The simplest way to run the application is on the command line like this:

$ export GCLOUD_KEY=<path-to-service-account-key.json>
$ export GCLOUD_PROJECT=<project-name>
$ dart bin/server.dart

This will serve the application at localhost:8080!

Running with Docker

To be closer to the production environment one can run the application inside a docker container. In order to do so, docker needs to be installed first (see the official instructions.

In order to run the application locally we uncomment the 3 lines in the Dockerfile and place the service account key in under app/key.json:

ADD key.json /project/key.json
ENV GCLOUD_KEY /project/key.json

We can then run the application via:

$ docker build .
Sucessfully built <docker-imgage-hash>
$ docker run -it <docker-imgage-hash>

In order to find out at which IP the Docker container is available we inspect the running container via:

$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
<container-id>       ...
app % docker inspect --format '{{ .NetworkSettings.IPAddress }}' <container-id>

Then the application will be available at


Before deploying the app, be sure to remove the environment variables in the Dockerfile which we used for local testing!

To deploy the application to the cloud we run the following command (optionally passing the --no-promote flag to avoid replacing the production version)

$ gcloud app deploy --no-promote app.yaml
Updating service [default]...done.
Deployed service [default] to [https://<version-id>-dot-<project-id>]

This will perform a remote docker build in the cloud and deploy a new version. You can find the URL to the version that got deployed in the output of gcloud app deploy (as well as via the Cloud Console under AppEngine > Versions).

Using memcache via memcached

By default, the memcacheService in package:appengine is a NOP – it does not perform any caching – unless a memcache service is found at the default port – localhost:11211.

App Engine Flexible Environment doesn't have a memcache service at the moment, but it is possible to simply install a memcached inside the Docker container.

Update the Dockerfile with the installation of memcached:

FROM ...

# We install memcached and remove the apt-index again to keep the
# docker image diff small.
RUN apt-get update && \
    apt-get install -y memcached && \
    rm -rf /var/lib/apt/lists/*


CMD []
ENTRYPOINT service memcached start && sleep 1 && /bin/bash /dart_runtime/

Using the datastore emulator

The gcloud sdk provides an easy-to-use datastore emulator. The emulator can be launched via

$ gcloud beta emulators datastore start
[datastore] If you are using a library that supports the DATASTORE_EMULATOR_HOST
[datastore] environment variable, run:
[datastore]   export DATASTORE_EMULATOR_HOST=localhost:8268
[datastore] Dev App Server is now running.

To make the application use the emulator, the DATASTORE_EMULATOR_HOST environment variable needs to be set (in addition to the other variables):

$ export DATASTORE_EMULATOR_HOST=localhost:8268
$ export GCLOUD_KEY=<path-to-service-account-key.json>
$ export GCLOUD_PROJECT=<project-name>
$ dart bin/server.dart


  • When logging requests, the label is populated.


  • When logging, the following protoPayload values are now populated:

    • instanceId
    • referrer
    • traceId via the X-Cloud-Trace-Context request header.
  • The label is also populated for all log entries.

  • traceId was also added to the ClientContext class.


  • Add support for connecting to memcache instance defined by environment variables GAE_MEMCACHE_HOST and GAE_MEMCACHE_PORT.


  • Add shared option to runAppEngine to enable multi-threaded operation with isolates.


  • Fix an issue where models with un-indexed list properties could not be committed.


  • Be less verbose in request logs printed during local development


Switch from Managed VMs to Flexible environment:

  • Removed UsersService api.
  • Removed ModulesService api.
  • Removed RemoteApi api (was already deprecated).
  • Introduce new GCLOUD_PROJECT and GCLOUD_KEY environment variables.
  • Remove STORAGE_SERVICE_ACCOUNT_FILE environment variable.
  • To prevent duplicate logging of errors, runAppEngine will no longer log request-specific errors on stdout if they got already logged via the request-specific log.


  • Support gcloud package version 0.3.0.


  • Work around issue (it doesn't drain stdout we therefore avoid printing anything).


  • Require protobuf package ^0.5.0
  • Support the lastest release of fixnum package.


  • Improved output of Logger.root with useLoggingPackageAdaptor.


  • Added optional port argument to runAppEngine.
  • Removed the call to /bin/hostname.


  • Widen dependency constraint on package:logging.


  • Pass the memcache expiration time to the memcache service. Before the expiration argument to Memcache.set and Memcache.setAll was ignored.

  • Removed the expiration argument to Memcache.clear. It is not supported by the App Engine memcache API.


  • Update dependencies to allow gcloud 0.2.0 with Cloud Pub/Sub support.


  • Do not close authClient, since registerStorageService does it automatically.


  • Correctly handling x-appengine-https header.
  • Turn logging of for Level.OFF


  • Added adaptor for package:logging via useLoggingPackageAdaptor().
  • Added workaround for incorrect requestedUri comming from 'dart:io'.


  • Added withAppEngineServices() function which allows running arbitrary code using AppEngine services via a service scope.


  • Change the service scope keys keys to non-private symbols.


  • Run request handlers inside a service scope (see package:gcloud/service_scope.dart).
  • Insert an authenticated HTTP client into the service scope.
  • Insert a memcacheService into the service scope.
  • Added isDevelopmentServer and isProductionEnvironment getter to client context.
  • Make hostnames returned from modules service use -dot- naming to support HTTPS.
  • Mark package:appengine/remote_api.dart as deprecated.


  • Small bugfix in the lowlevel memcache API implementation.


  • Updated
  • Widen googleapis_auth constraint to include version 0.2.0


  • Small bugfix in storage API implementation
  • respect DART_PUB_SERVE url only in developer mode
  • sync db/datastore tests to the ones used in gcloud


  • Use datastore/db APIs from package:gcloud
    • simplified annotation system
    • paging-based query API
  • Added module service
  • Some bugfixes


  • Alpha release

1. Depend on it

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

  appengine: "^0.4.3+1"

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:appengine/appengine.dart';
Version Uploaded Documentation Archive
0.4.3+1 Nov 30, 2017 Go to the documentation of appengine 0.4.3+1 Download appengine 0.4.3+1 archive
0.4.3 Nov 30, 2017 Go to the documentation of appengine 0.4.3 Download appengine 0.4.3 archive
0.4.2 Sep 8, 2017 Go to the documentation of appengine 0.4.2 Download appengine 0.4.2 archive
0.4.1 Jul 28, 2017 Go to the documentation of appengine 0.4.1 Download appengine 0.4.1 archive
0.4.0+3 May 4, 2017 Go to the documentation of appengine 0.4.0+3 Download appengine 0.4.0+3 archive
0.4.0+2 Apr 28, 2017 Go to the documentation of appengine 0.4.0+2 Download appengine 0.4.0+2 archive
0.4.0+1 Apr 3, 2017 Go to the documentation of appengine 0.4.0+1 Download appengine 0.4.0+1 archive
0.4.0 Apr 3, 2017 Go to the documentation of appengine 0.4.0 Download appengine 0.4.0 archive
0.3.3+1 Aug 29, 2016 Go to the documentation of appengine 0.3.3+1 Download appengine 0.3.3+1 archive
0.3.3 Jan 28, 2016 Go to the documentation of appengine 0.3.3 Download appengine 0.3.3 archive

All 36 versions...


This feature is new.
We welcome feedback.
More details: scoring.

We analyzed this package, and provided a score, details, and suggestions below.

  • tool failures on Feb 22, 2018
  • Dart: 2.0.0-dev.20.0
  • pana: 0.10.1


Describes how popular the package is relative to other packages. [more]
81 / 100
Code health derived from static analysis. [more]
73 / 100
Reflects how tidy and up-to-date the package is. [more]
95 / 100
Overall score:
Weighted score of the above. [more]


Detected platforms: other

Primary library: package:appengine/appengine.dart with components: io, mirrors.


  • Fix lib/src/grpc_api_impl/grpc.dart.

    Strong-mode analysis of lib/src/grpc_api_impl/grpc.dart failed with the following error:

    line: 179 col: 71
    The getter 'headers' isn't defined for the class 'StreamMessage'.

  • Fix issues reported by dartanalyzer.

    dartanalyzer reported 1 error(s) and 0 warning(s).

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use appengine.dart.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.22.0 <2.0.0
fixnum >=0.9.0 <0.11.0 0.10.7
gcloud >=0.4.0 <0.5.0 0.4.0+1
googleapis_auth >=0.2.3+6 <0.3.0 0.2.4
http ^0.11.3+9 0.11.3+16
http2 ^0.1.1+2 0.1.7
http_server ^0.9.2 0.9.7
logging >=0.9.3 <0.12.0 0.11.3+1
memcache ^0.2.1+1 0.2.1+2
path ^1.2.0 1.5.1
protobuf ^0.5.0 0.5.5 0.7.1
Transitive dependencies
_discoveryapis_commons 0.1.5
async 2.0.3 2.0.4
charcode 1.1.1
collection 1.14.5
convert 2.0.1
crypto 2.0.2+1
googleapis 0.44.0 0.50.0
googleapis_beta 0.39.2 0.45.0
http_parser 3.1.1
mime 0.9.6
source_span 1.4.0
string_scanner 1.0.2
typed_data 1.1.5
Dev dependencies
test ^0.12.18+1