Skip to content

Latest commit

 

History

History
118 lines (85 loc) · 3.83 KB

development.md

File metadata and controls

118 lines (85 loc) · 3.83 KB

Developing pub.dev

pub.dev runs on Google AppEngine, but we also support a local, in-memory server that is able to run 95-99% of the site on a single machine, without any need for AppEngine account or setup.

  • If you want to contribute to pub.dev, the current document will give you instructions how to work with the local, in-memory server (fake_server).

  • If you want to setup the project on Google AppEngine, follow this guide.

  • Development and runtime support is best on Linux, compatible system may work, Windows isn't supported yet (e.g. bash scripts are not compatible).

Project structure

The main directories that one would be looking at:

  • app/: contains the main server application.
  • pkg/web_app: contains the client-side part of the app.
  • pkg/web_css: contains the SCSS files.
  • static: contains static files and images deployed alongside the app.
  • third_party: contains 3rd-party assets that are deployed alongside the app.

Initial data

The in-memory server starts with no data. Prepopulated data can be created with test-profiles, using the following steps:

Create a test-profile description

A test-profile is a short description of packages, publishers, users, their flags and relations.

To create an initialize it with some minimal data, create the following YAML file:

defaultUser: 'your-email@example.com'
importedPackages:
  - name: retry
  - name: http
publishers:
  - # Only `example.com`` and `verified.com`` will verify.
    # See app/lib/fake/backend/fake_domain_verifier.dart
    name: example.com
    members:
      - email: your-email@example.com
        role: admin

Process and create data file

Using the test-profile above, the following process will:

  • create the publishers and users.
  • fetch the latest versions and the archive file from pub.dev.
  • publish the archive locally under the name of the user or the publisher in the test-profile description.
  • analyze the packages and runs dartdoc on them
  • stores the results and all the entities in a local file.
cd app/
dart bin/fake_server.dart init-data-file \
  --test-profile=[the file you have created] \
  --analysis=[ none | fake | local | worker ] \
  --data-file=dev-data-file.jsonl
  • fake analysis will use a deterministic, but random-looking process to create analysis results quickly.
  • local analysis will use the locally available SDKs from PATH.
  • worker analysis will run pana and dartdoc inside a docker container, similarly as the production server would run them, using the configured SDK versions.

Using the fake server with the data file

After the data file has been created, you can start using it locally:

cd app/
dart bin/fake_server.dart run --data-file=dev-data-file.jsonl

The fake_server.dart script picks up changes and rebuilds your style sheets when initializing.

Local accounts

The web app and the API endpoints use a simple mechanism to map access tokens to authenticated accounts: user-at-domain-dot-com gets mapped to user@domain.com.

  • On the web app, use localhost:8080/sign-in?fake-email=your-email@example.com to sign in.
  • On the API endpoints one should send the Authorization header with Bearer $token as value.

Updating generated code

The application and various packages uses builders to generate code based on source annotations. Input files are usually listed in build.yaml, and generated files usually suffixed .g.dart. To generate code use:

./tool/codegen.sh

Update/upgrade dependencies

Run pub upgrade in the root to upgrade the entire workspace:

dart pub upgrade

Creating a new package (or vendoring existing packages)

  1. Include the package in the root-level workspace.

  2. Use resolution: workspace in the new package's pubspec.yaml.