Atmosphere Package Repository

Understanding Meteor’s package ecosystem and repository

Atmosphere is Meteor’s package repository, hosting thousands of community and core packages. It’s accessible at atmospherejs.com.

What is Atmosphere?

Atmosphere is the central registry for Meteor packages, similar to npm for Node.js. It provides:

• Package hosting: Stores and distributes Meteor packages
• Version management: Tracks all versions of every package
• Dependency resolution: Helps Meteor’s constraint solver find compatible versions
• Package discovery: Browse and search thousands of packages
• Usage statistics: Track package downloads and popularity

Package Naming Convention

Atmosphere packages use a namespaced naming system:

username:package-name

Examples:

• iron:router - Iron Router by the Iron team
• aldeed:collection2 - Collection2 by aldeed
• ostrio:flow-router-extra - Flow Router Extra by ostrio

Core Packages

Core packages maintained by Meteor don’t use a namespace:

• accounts-base
• mongo
• tracker
• ecmascript

These live in the packages/ directory of the Meteor repository.

Using Atmosphere Packages

Adding a Package

meteor add username:package-name

Examples:

meteor add aldeed:collection2
meteor add ostrio:flow-router-extra@3.9.0  # Specific version
meteor add meteor-base  # Core package

Removing a Package

meteor remove username:package-name

Updating Packages

meteor update                     # Update all packages
meteor update username:package    # Update specific package
meteor update --all-packages      # Force update all

Searching for Packages

meteor search router

Or browse at atmospherejs.com.

Listing Installed Packages

meteor list

Or check .meteor/packages in your app.

Package Metadata

Meteor provides a DDP API at packages.meteor.com to query package information.

Available Data

The package server exposes several collections:

Packages Collection

One record per package:

{
  name: "iron:router",
  maintainers: [{ username: "iron" }],
  homepage: "https://github.com/iron-meteor/iron-router",
  lastUpdated: Date
}

Versions Collection

One record per package version:

{
  packageName: "iron:router",
  version: "1.1.0",
  description: "Routing for Meteor",
  longDescription: "...",
  git: "https://github.com/iron-meteor/iron-router.git",
  dependencies: {
    "meteor": { constraint: "1.0.0" },
    "underscore": { constraint: "1.0.0" }
  },
  exports: [
    { name: "Router", architectures: ["os", "browser.web"] }
  ],
  publishedBy: { username: "iron" },
  published: Date
}

Builds Collection

One record per architecture build:

{
  versionId: "...",
  buildArchitectures: "os.linux.x86_64+web.browser+web.cordova",
  build: {
    url: "https://...",
    tarballHash: "sha256...",
    treeHash: "sha256..."
  },
  builtBy: { username: "iron" },
  buildPublished: Date
}

Querying Package Data

Connect via DDP:

const connection = DDP.connect('https://packages.meteor.com');

connection.call('syncNewPackageData', syncToken, (error, result) => {
  console.log(result.collections.packages);    // Up to 500 package records
  console.log(result.collections.versions);    // Up to 500 version records
  console.log(result.collections.builds);      // Up to 500 build records
});

Package Statistics

Meteor tracks daily package installation statistics.

Accessing Stats

HTTP GET request:

https://packages.meteor.com/stats/v1/YYYY-MM-DD

Example:

https://packages.meteor.com/stats/v1/2024-01-15

Stats Format

JSON objects separated by newlines:

{ "name": "tracker", "version": "1.3.4", "directAdds": 250, "totalAdds": 1000 }
{ "name": "iron:router", "version": "1.1.0", "directAdds": 200, "totalAdds": 800 }

Fields:

• name: Package name
• version: Version installed
• directAdds: Times directly added via meteor add
• totalAdds: Total adds including as a dependency

Stats Subscription

Subscribe to available date range:

connection.subscribe('stats');

// Exposes 'stats' collection with:
{
  earliest: "2015-01-01",
  latest: "2024-01-15"
}

Package Discovery

Popular Categories

• Routing: ostrio:flow-router-extra, kadira:flow-router
• Forms: aldeed:collection2, aldeed:autoform
• Authentication: accounts-password, accounts-google
• Testing: meteortesting:mocha, xolvio:cleaner
• UI: blaze-html-templates, react-meteor-data
• Build Tools: typescript, less, sass
• Mobile: Cordova plugin packages
• Security: audit-argument-checks, browser-policy

Finding Quality Packages

Look for:

1. Active maintenance: Recent updates
2. Good documentation: Clear README and examples
3. High usage: Download statistics
4. Test coverage: Test files included
5. Semantic versioning: Proper version management
6. GitHub repository: Open source with issue tracking

Version Constraints

Atmosphere uses Meteor’s constraint solver with semantic versioning.

Constraint Rules

1. Major version must match exactly:

   api.use('iron:router@1.0.0');  // Accepts 1.x.x, not 2.x.x
   

2. Minor and patch must be >=:

   api.use('iron:router@1.2.3');  // Accepts 1.2.3, 1.2.4, 1.3.0
   

3. Single-loading: Only one version per app

4. Gravity: Solver prefers oldest compatible version

Version Syntax

// Exact version
api.use('iron:router@1.0.0');

// Minimum version
api.use('iron:router@1.2.0');

// Multiple major versions
api.use('blaze@1.0.0 || 2.0.0');

// No version (use from versionsFrom)
api.versionsFrom('1.12.1');
api.use('tracker');  // Uses version from Meteor 1.12.1

Package Resolution

Meteor looks for packages in this order:

1. Local packages: packages/ directory in your app
2. METEOR_PACKAGE_DIRS: Environment variable paths
3. Atmosphere: Downloaded to ~/.meteor/packages

Overriding Atmosphere Packages

Place a local version in packages/ to override:

my-app/
├── packages/
│   └── iron:router/     # Local override
│       └── package.js
└── .meteor/
    └── packages         # Lists iron:router

This is useful for:

• Testing modifications
• Patching bugs before upstream fixes
• Customizing for your app

npm vs Atmosphere

When to Use Atmosphere

• Meteor-specific functionality
• Client-server integration
• Meteor build system integration
• Meteor API dependencies (DDP, Tracker, etc.)

When to Use npm

• Pure JavaScript libraries
• Node.js modules
• React/Vue/Angular components
• Utilities without Meteor dependencies

Using Both

Atmosphere packages can depend on npm packages:

// In package.js
Npm.depends({
  'lodash': '4.17.21',
  'moment': '2.29.1'
});

And apps can use both:

meteor add reactive-var        # Atmosphere
npm install react react-dom    # npm

Popular Atmosphere Packages

Routing

• ostrio:flow-router-extra - Client-side router
• iron:router - Classic Meteor router (deprecated)

Data & Collections

• aldeed:collection2 - Schema validation for collections
• reywood:publish-composite - Reactive joins
• dburles:collection-helpers - Transform helpers

Forms

• aldeed:autoform - Automatic form generation
• vazco:uniforms - Modern forms framework

Authentication

• accounts-password - Password authentication (core)
• accounts-google - Google OAuth (core)
• accounts-facebook - Facebook OAuth (core)

Testing

• meteortesting:mocha - Mocha test framework
• xolvio:cleaner - Database cleanup for tests
• johanbrook:publication-collector - Test publications

Development Tools

• msavin:mongol - MongoDB admin interface
• meteorhacks:kadira - Performance monitoring
• bundle-visualizer - Analyze bundle size (core)

UI Frameworks

• blaze-html-templates - Blaze templating (core)
• react-meteor-data - React integration (core)
• vue-meteor-tracker - Vue integration

Package Best Practices

For Package Authors

1. Clear naming: Use descriptive package names
2. Good documentation: README with examples
3. Semantic versioning: Follow SemVer strictly
4. Test coverage: Include tests
5. Dependency management: Minimize dependencies
6. Backwards compatibility: Don’t break existing APIs

For Package Users

1. Check maintenance: Avoid abandoned packages
2. Review code: Check source before using
3. Pin versions: Use specific versions in production
4. Monitor updates: Keep packages updated
5. Report issues: Help maintainers improve

Package Security

Security Considerations

1. Review package code: Packages have full app access
2. Check maintainers: Trust verified authors
3. Audit dependencies: Check npm dependencies too
4. Report vulnerabilities: Email [e-mail]
5. Keep updated: Security fixes in new versions

Insecure Packages

Some packages are for development only:

# NEVER use in production!
meteor add insecure      # Allows all database writes
meteor add autopublish   # Publishes all data

Remove before deploying:

meteor remove insecure autopublish

Troubleshooting

Package not found

Check:

• Package name spelling
• Package exists on Atmosphere
• Network connectivity

Try:

meteor search package-name

Version constraint conflicts

error: conflict: two packages included in the app
(ostrio:flow-router-extra and kadira:flow-router)
are both trying to use different versions of the same
core package

Solution: Choose one package or upgrade both to compatible versions.

Package fails to build

• Try removing and re-adding: meteor remove pkg && meteor add pkg
• Clear cache: rm -rf ~/.meteor/packages
• Check for binary dependencies needing specific architecture

Old package versions

Force update:

meteor update --all-packages

Or specify version:

meteor add username:package@1.2.0

Atmosphere API Example

Query package information programmatically:

import { DDP } from 'meteor/ddp-client';

const packagesConnection = DDP.connect('https://packages.meteor.com');

// Subscribe to defaults to get sync token
packagesConnection.subscribe('defaults');

// Get package data
packagesConnection.call(
  'syncNewPackageData',
  syncToken,
  (error, result) => {
    if (error) {
      console.error('Error fetching packages:', error);
      return;
    }
    
    const { collections, upToDate, syncToken: newToken } = result;
    
    // Process packages
    collections.packages.forEach(pkg => {
      console.log(`${pkg.name} - ${pkg.maintainers[0].username}`);
    });
    
    // Process versions
    collections.versions.forEach(version => {
      console.log(`${version.packageName}@${version.version}`);
    });
    
    if (!upToDate) {
      // Call again with newToken to get more data
    }
  }
);

Future of Atmosphere

Meteor continues to support both Atmosphere and npm:

• Atmosphere: Meteor-specific packages
• npm: General JavaScript packages
• Hybrid approach: Use best tool for each need

Many new Meteor packages publish to both npm and Atmosphere for broader reach.

Next Steps

Creating Packages

Build your own package

Publishing Packages

Share your package on Atmosphere

Package Server API

Complete API documentation

Browse Packages

Explore Atmosphere packages