> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/meteor/meteor/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://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](https://github.com/meteor/meteor/tree/devel/packages).

## Using Atmosphere Packages

### Adding a Package

```bash theme={null}
meteor add username:package-name
```

Examples:

```bash theme={null}
meteor add aldeed:collection2
meteor add ostrio:flow-router-extra@3.9.0  # Specific version
meteor add meteor-base  # Core package
```

### Removing a Package

```bash theme={null}
meteor remove username:package-name
```

### Updating Packages

```bash theme={null}
meteor update                     # Update all packages
meteor update username:package    # Update specific package
meteor update --all-packages      # Force update all
```

### Searching for Packages

```bash theme={null}
meteor search router
```

Or browse at [atmospherejs.com](https://atmospherejs.com).

### Listing Installed Packages

```bash theme={null}
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:

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

#### Versions Collection

One record per package version:

```javascript theme={null}
{
  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:

```javascript theme={null}
{
  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:

```javascript theme={null}
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:

```json theme={null}
{ "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:

```javascript theme={null}
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**:
   ```javascript theme={null}
   api.use('iron:router@1.0.0');  // Accepts 1.x.x, not 2.x.x
   ```

2. **Minor and patch must be >=**:
   ```javascript theme={null}
   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

```javascript theme={null}
// 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:

```bash theme={null}
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:

```javascript theme={null}
// In package.js
Npm.depends({
  'lodash': '4.17.21',
  'moment': '2.29.1'
});
```

And apps can use both:

```bash theme={null}
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 [security@meteor.com](mailto:security@meteor.com)
5. **Keep updated**: Security fixes in new versions

### Insecure Packages

Some packages are for development only:

```bash theme={null}
# NEVER use in production!
meteor add insecure      # Allows all database writes
meteor add autopublish   # Publishes all data
```

Remove before deploying:

```bash theme={null}
meteor remove insecure autopublish
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Package not found">
    Check:

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

    Try:

    ```bash theme={null}
    meteor search package-name
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Old package versions">
    Force update:

    ```bash theme={null}
    meteor update --all-packages
    ```

    Or specify version:

    ```bash theme={null}
    meteor add username:package@1.2.0
    ```
  </Accordion>
</AccordionGroup>

## Atmosphere API Example

Query package information programmatically:

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Creating Packages" icon="plus" href="/packages/creating">
    Build your own package
  </Card>

  <Card title="Publishing Packages" icon="upload" href="/packages/publishing">
    Share your package on Atmosphere
  </Card>

  <Card title="Package Server API" icon="server" href="/packages/atmosphere#package-metadata">
    Complete API documentation
  </Card>

  <Card title="Browse Packages" icon="globe" href="https://atmospherejs.com">
    Explore Atmosphere packages
  </Card>
</CardGroup>