Meteor Package System

Understanding Meteor’s modular package architecture, core packages, and Atmosphere ecosystem

Overview

Meteor uses a powerful package system that enables modular application development. Packages can contain JavaScript, CSS, assets, and even build plugins that extend the build system.

Meteor has over 140 core packages and thousands of community packages available through Atmosphere.

Package Types

Core Packages

Core packages are maintained in the official Meteor repository at packages/. They are:

• Released together with Meteor tool versions
• Don’t have .versions files (always released from checkout)
• Located directly in packages/ (not in subdirectories)

List Core Packages

# From the Meteor repository root
ls packages/

# Example output:
accounts-base/
accounts-password/
ddp/
ddp-client/
ddp-server/
mongo/
minimongo/
tracker/
reactive-var/
...

# Add a core package to your app
meteor add accounts-password
meteor add mongo
meteor add tracker

Non-Core Packages

Packages in packages/non-core/ or packages/deprecated/ are:

• Not considered core packages
• May have different release schedules
• Often for backwards compatibility

Examples: jquery, coffeescript, less, mongo-decimal

Community Packages

Published to Atmosphere by the community:

meteor add username:package-name

npm Packages

Meteor fully supports npm packages:

meteor npm install react react-dom

Package Structure

Every Meteor package has a package.js file that defines its metadata and configuration.

Basic package.js

package.js

Package.describe({
  name: 'myusername:mypackage',
  version: '1.0.0',
  summary: 'A short description of the package',
  git: 'https://github.com/myusername/mypackage',
  documentation: 'README.md'
});

Package.onUse(function(api) {
  // Minimum Meteor version
  api.versionsFrom('3.0');
  
  // Dependencies
  api.use('ecmascript');
  api.use('mongo');
  
  // Export symbols
  api.export('MyAPI');
  
  // Add files
  api.addFiles('mypackage.js');
});

Package.onTest(function(api) {
  api.use('ecmascript');
  api.use('tinytest');
  api.use('myusername:mypackage');
  
  api.addFiles('mypackage-tests.js');
});

Real Example: meteor Package

The core meteor package (packages/meteor/package.js):

Package.describe({
  summary: "Core Meteor environment",
  version: '2.2.0',
});

Package.registerBuildPlugin({
  name: "basicFileTypes",
  sources: ['plugin/basic-file-types.js']
});

Package.onUse(function (api) {
  api.use('isobuild:compiler-plugin@1.0.0');
  api.use('core-runtime');

  api.export('Meteor');
  api.export('global');

  api.addFiles('global.js', ['client', 'server']);
  api.addFiles('client_environment.js', 'client');
  api.addFiles('server_environment.js', 'server');
  api.addFiles('helpers.js', ['client', 'server']);
  api.addFiles('timers.js', ['client', 'server']);
  // ... more files
});

Real Example: DDP Package

The ddp package demonstrates package composition:

packages/ddp/package.js

Package.describe({
  summary: "Meteor's latency-compensated distributed data framework",
  version: '1.4.2',
});

Package.onUse(function (api) {
  // Use other packages
  api.use(['ddp-client'], ['client', 'server']);
  api.use(['ddp-server'], 'server');

  api.addAssets('ddp.d.ts', 'server');

  api.export('DDP');
  api.export('DDPServer', 'server');

  // Make dependencies available to users
  api.imply('ddp-client');
  api.imply('ddp-server');
});

Package API

The package.js API provides several key methods:

Package.describe

Defines package metadata:

Package.describe({
  name: 'username:package',      // Unique identifier
  version: '1.0.0',              // Semantic version
  summary: 'Short description',  // Max 100 chars
  git: 'https://...',            // Git repository
  documentation: 'README.md'     // Docs file
});

api.use

Declares dependencies:

// Single package
api.use('mongo');

// Multiple packages
api.use(['mongo', 'tracker', 'reactive-var']);

// With version constraints
api.use('ddp@1.4.0');

// Architecture-specific
api.use('accounts-base', 'server');
api.use('tracker', ['client', 'server']);

// Weak dependency (optional)
api.use('jquery', { weak: true });

api.imply

Makes dependencies available to package users:

// When users add your package, they also get these
api.imply('modules');
api.imply('ecmascript-runtime');
api.imply('babel-runtime');
api.imply('promise');

Example from ecmascript package:

packages/ecmascript/package.js

Package.onUse(function(api) {
  api.use('isobuild:compiler-plugin@1.0.0');
  api.use('react-fast-refresh');

  // These packages are implied - users get them automatically
  api.imply('modules');
  api.imply('ecmascript-runtime');
  api.imply('babel-runtime');
  api.imply('promise');
  api.imply('dynamic-import');
});

api.export

Exports symbols globally:

// Export to all architectures
api.export('MyAPI');

// Export to specific architecture
api.export('ServerAPI', 'server');
api.export('ClientAPI', 'client');

// Export multiple symbols
api.export(['API1', 'API2']);

api.addFiles

Adds source files to the package:

// Add to all architectures
api.addFiles('common.js');

// Add to specific architectures
api.addFiles('client.js', 'client');
api.addFiles('server.js', 'server');
api.addFiles('shared.js', ['client', 'server']);

// Add with options
api.addFiles('bare.js', 'client', { bare: true });

api.addAssets

Adds non-JS files:

// TypeScript definitions
api.addAssets('meteor.d.ts', 'server');

// Templates, JSON, etc.
api.addAssets('template.html', 'client');

Core Package Domains

Meteor’s 140+ core packages are organized by functionality:

Authentication & Accounts

accounts-base

Core authentication system

Meteor.user()
Meteor.userId()
Meteor.users

accounts-password

Username/password authentication

Accounts.createUser()
Meteor.loginWithPassword()

accounts-oauth

OAuth integration base

accounts-2fa

Two-factor authentication

OAuth providers: accounts-google, accounts-facebook, accounts-github, accounts-twitter, etc.

Database & Data

mongo

MongoDB driver and collections

new Mongo.Collection('items')

minimongo

Client-side MongoDB implementation

ddp-server

Server-side DDP implementation

ddp-client

Client-side DDP implementation

Build & Compilation

ecmascript

ES2015+ compilation via Babel

babel-compiler

Babel integration for build plugins

typescript

TypeScript support

rspack

Modern bundler integration

Reactivity

tracker

Reactive computation system

Tracker.autorun(() => {})

reactive-var

Single reactive value

new ReactiveVar(initialValue)

reactive-dict

Reactive key-value store

new ReactiveDict()

session

Global reactive dictionary

Session.set('key', value)

Web Server

webapp

HTTP server (Express-based)

WebApp.connectHandlers

autoupdate

Hot code push to clients

reload

Client reload coordination

server-render

Server-side rendering support

Build Plugins

Packages can register build plugins that extend the build system:

Compiler Plugin

Package.registerBuildPlugin({
  name: 'compile-ecmascript',
  use: ['babel-compiler', 'react-fast-refresh'],
  sources: ['plugin.js'],
});

Plugin Types

Compiler Plugin

Compiles source files (e.g., .jsx, .ts, .vue)

Plugin.registerCompiler({
  extensions: ['jsx'],
  filenames: ['component.jsx']
}, () => new MyCompiler());

Minifier Plugin

Minifies JavaScript and CSS

Plugin.registerMinifier({
  extensions: ['js']
}, () => new MyMinifier());

Linter Plugin

Lints source code during build

Plugin.registerLinter({
  extensions: ['js']
}, () => new MyLinter());

npm Dependencies

Packages can declare npm dependencies:

Npm.depends({
  'denque': '2.1.0',
  '@babel/runtime': '7.20.7'
});

From the meteor package:

packages/meteor/package.js

Npm.depends({
  "denque": "2.1.0"
});

Package Dependencies Resolution

Meteor uses a constraint solver to determine package versions:

1. Reads package constraints from .meteor/packages
2. Resolves compatible versions using constraint solver
3. Writes resolved versions to .meteor/versions
4. Downloads and caches packages

.meteor/packages

# Direct dependencies
meteor-base@1.5.2
mongo@2.0.0
reactive-var@1.0.13

.meteor/versions

# Fully resolved dependency tree
allow-deny@1.1.1
autoupdate@2.0.0
base64@1.0.13
binary-heap@1.0.12
...

Creating Packages

Local Package

Create a package in your app:

meteor create --package username:mypackage

This creates:

packages/
└── username:mypackage/
    ├── package.js
    ├── mypackage.js
    ├── mypackage-tests.js
    └── README.md

Publishing to Atmosphere

# Login to Meteor account
meteor login

# Publish package
meteor publish

# Publish release
meteor publish-release

Best Practices

Minimize Dependencies

Only depend on packages you actually need. Each dependency adds to bundle size and complexity.

// Good - minimal dependencies
api.use(['ecmascript', 'mongo']);

// Avoid - unnecessary dependencies
api.use(['ecmascript', 'mongo', 'jquery', 'underscore', ...]);

Use api.imply Carefully

Only imply packages that are part of your public API:

// Good - users need these
api.imply('ddp-client');

// Avoid - internal dependency
api.use('some-helper');  // Not imply

Version Constraints

Specify version constraints for stability:

api.use('ddp@1.4.0');           // Exact version
api.use('mongo@2.0.0');         // Compatible updates
api.versionsFrom('3.0');        // Minimum Meteor version

Architecture Targeting

Be explicit about where code runs:

api.addFiles('server-only.js', 'server');
api.addFiles('client-only.js', 'client');
api.addFiles('shared.js', ['client', 'server']);

Next: Isobuild

Learn how Meteor’s build system compiles and packages your code