---

title: Packages description: Which Poptart package to use for each kind of consumer project. #

Package Decision Guide #

Pick the highest-level package that matches what you are building.

If you are building...	Add...	Why
A Dart or Flutter app that talks to AT Protocol services	poptart	The normal app surface: one client, sessions, OAuth helpers, raw XRPC, and common protocol primitives. Add the generated lexicon package for the namespaces you call.
An app or library that needs generated com.atproto.* descriptors or record types	poptart_lex	Use exact generated barrels for ATProto base records, methods, generated IDs, and bundled lexicon documents.
An app or library that needs generated Bluesky descriptors or record types	bluesky_poptart	Generated app.bsky.* and chat.bsky.* methods, records, IDs, and lexicon documents.
A moderation tool that needs Ozone lexicons	ozone_poptart	Generated tools.ozone.* methods, records, IDs, and lexicon documents.
A Spark app or integration	sprk_poptart	Generated so.sprk.* methods, records, IDs, and lexicon documents.
A Margin app or integration	margin_poptart	Generated at.margin.* methods, records, IDs, and lexicon documents.
A tool that parses raw Lexicon documents	poptart_lexicon	Parser-only package with LexiconDoc and schema model types.
A Flutter app with AT Protocol OAuth sign-in	poptart_oauth	OAuth authorization, callback, refresh, DPoP key material, and session helpers.
A tool that validates handles, DIDs, AT URIs, or NSIDs	poptart_primitives	Small protocol primitive package with validation and parsing helpers.
A low-level XRPC wrapper or custom client	poptart_xrpc	Raw query/procedure helpers when generated descriptors are not the right fit.
A DID PLC directory integration	poptart_did_plc	Independent client for DID documents, operation logs, audit logs, caching, and streaming.
A CID or IPFS-related parser	poptart_multiformats	Multiformat helpers used by higher-level protocol packages.

Use poptart In Apps #

The umbrella package is intentionally boring for consumers: install one package and import one file.

import 'package:poptart/poptart.dart';

Future<void> printProfile(String actor) async {
  final client = PoptartClient.anonymous();
  final profile = await client.get<Map<String, dynamic>>(
    NSID.parse('app.bsky.actor.getProfile'),
    parameters: {'actor': actor},
  );

  print(profile.data['handle']);
}

Generated lexicon calls are preferred for new code. Use the generated method value when you want app-style call sites, or pass methodDescriptor when you want the explicit lower-level descriptor. Raw XRPC calls are still available through PoptartClient.get, PoptartClient.post, and the lower-level poptart_xrpc package.

Use Focused Packages In Libraries #

Focused packages are useful when you want your own public API to expose only one protocol layer.

dependencies:
  poptart_primitives: ^0.1.0

import 'package:poptart_primitives/at_primitives.dart';

bool canAcceptRepo(String value) {
  return isValidHandle(value) || isValidDid(value);
}

Focused imports also make it clearer what your package promises to support. For example, a parser package should usually depend on poptart_primitives or poptart_lexicon, while generated protocol code should depend on the package that owns the namespace it imports.

Generated Lexicon Barrels #

poptart exports the app-facing client and app-password session helpers. Each generated lexicon package exports one public barrel per lexicon method or record. Import the focused barrel for the exact schema you use.

import 'package:bluesky_poptart/app/bsky/feed/post.dart' as feed_post;
import 'package:poptart_lex/com/atproto/repo/create_record.dart'
    as create_record;

final record = feed_post.FeedPostRecord(
  text: 'Hello from Dart',
  createdAt: DateTime.now().toUtc(),
);

final input = create_record.RepoCreateRecordInput(
  repo: 'did:plc:example',
  collection: 'app.bsky.feed.post',
  record: record.toJson(),
);

This keeps imports explicit and avoids dragging a huge generated namespace into every file.