github/meteor
1
1
Fork 0
mirror of https://github.com/meteor/meteor.git synced 2026-05-02 03:01:46 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/release-3.4.1' into release-3.4.1

Browse Source
This commit is contained in:
Nacho Codoñer
2026-02-09 16:59:23 +01:00
parent a8a4cb5c48 0b40068463
commit 6182e0af0b
8 changed files with 1025 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
.github/skills/ai-context/SKILL.md vendored Normal file
View File

@@ -0,0 +1,111 @@
---
name: ai-context
description: Use when creating, updating, or maintaining AI documentation files (AGENTS.md, CLAUDE.md, skills). Covers file structure, conventions, and guidelines for evolving AI context.
---
# AI Context Documentation
How to write and maintain the structured documentation that AI coding assistants consume.
## File Hierarchy
```
AGENTS.md # Root context — always loaded by agents
CLAUDE.md # Required for Claude Code (loads AGENTS.md)
.github/skills/<topic>/SKILL.md # On-demand detailed context
packages/<name>/AGENTS.md # Package-specific context
<any-folder>/AGENTS.md # Folder-specific context
```
## Root Files
### AGENTS.md
Always loaded on every interaction. Keep it **minimal** to save tokens.
Must contain:
- One-line project description
- Essential commands (run, test, build)
- Repository structure overview (top-level dirs only)
- Skills index table linking to each `SKILL.md`
- Key entry points for common tasks
Must **not** contain:
- Detailed explanations (put those in skills)
- Code examples longer than one line
- Duplicated content from skills
### CLAUDE.md
Required because Claude Code doesn't load `AGENTS.md` natively. It bridges Claude Code into the same context system. Contents:
```markdown
Read [AGENTS.md](AGENTS.md) before starting any task.
## Skills
Load these for detailed context on specific topics:
| Skill | When to use |
|-------|-------------|
| [<name>](.github/skills/<name>/SKILL.md) | <description> |
```
Keep in sync with the skills table in `AGENTS.md`.
## Skills
### Creating a Skill
1. Create `.github/skills/<topic>/SKILL.md`
2. Add YAML frontmatter with `name` and `description`
3. Add an entry to the skills table in both `AGENTS.md` and `CLAUDE.md`
### SKILL.md Format
```markdown
---
name: <topic>
description: <when an agent should load this — be specific about triggers>
---
# <Title>
<One-line summary.>
## <Sections organized by task>
```
### Writing Guidelines
- **Frontmatter `description`**: Write it as a trigger — what task or question should cause an agent to load this skill
- **Be concise**: Use tables over prose, code snippets over explanations
- **Be specific**: File paths, command names, function signatures — not vague descriptions
- **No duplication**: If info exists in another skill, reference it instead of repeating
- **Actionable structure**: Organize by what the agent needs to *do*, not by architecture
## Package & Folder Context
Add `AGENTS.md` inside a package or folder when:
- The directory has non-obvious conventions agents keep getting wrong
- There are local commands, patterns, or gotchas not covered by root docs
Keep these files very short — a few lines of context is often enough.
## When to Update
| Trigger | Action |
|---------|--------|
| Agent repeatedly asks about a topic | Create a new skill |
| Agent gets something wrong despite docs | Refine the relevant skill |
| New package/directory with unique patterns | Add a local `AGENTS.md` |
| Architecture or tooling changes | Update affected skills |
| Skill grows too large | Split into multiple skills |
| Skills table changes | Update both `AGENTS.md` and `CLAUDE.md` |
## Principles
1. **Token budget**: Root files stay small; details go in skills
2. **Load on demand**: Skills are only read when relevant to the task
3. **Living docs**: Update when patterns change — stale docs are worse than none
4. **Cross-platform**: `AGENTS.md` + `.github/skills/` is the shared convention; `CLAUDE.md` bridges Claude Code which doesn't load `AGENTS.md` natively

110
.github/skills/codebase/SKILL.md vendored Normal file
View File

@@ -0,0 +1,110 @@
---
name: codebase
description: Use when understanding the build system, modifying CLI commands, working with isobuild, or navigating the tools/ directory. Covers build pipeline flow and file locations.
---
# Codebase
Meteor's build system (Isobuild) and CLI structure.
## Overview
Meteor is a full-stack JavaScript platform with:
- **Core packages** in `/packages`
- **Build system (Isobuild)** in `/tools/isobuild`
- **CLI tool** in `/tools/cli`
- **Real-time data layer** via DDP
- **Mobile support** via Cordova
## Build Pipeline
1. **CLI** (`tools/cli/main.js`) → parses commands
2. **Project Context** (`project-context.js`) → resolves packages, dependencies
3. **Isobuild** (`tools/isobuild/`)
- Bundler (`bundler.js`) → orchestrates build
- Compiler (`compiler.js`) → compiles packages
- Linker (`linker.js`) → wraps modules
- Build plugins (Babel, TypeScript, CSS)
4. **Output** → `star.json`, programs
5. **Runners** (`tools/runners/`) → run-app.js, run-mongo.js, run-hmr.js
6. **Live App** → DDP Server ↔ Minimongo ↔ UI
## Directory Structure
```
tools/
├── cli/ # Command-line interface
├── isobuild/ # Build system core
├── packaging/ # Package management
├── runners/ # App execution engines
├── fs/ # File system utilities
├── cordova/ # Mobile/Cordova support
├── static-assets/ # Project templates
└── project-context.js # Dependency resolution
```
## CLI (`tools/cli/`)
| File | Description |
|------|-------------|
| `main.js` | Entry point, command dispatcher |
| `commands.js` | Main command implementations |
| `commands-packages.js` | Package management commands |
| `commands-cordova.js` | Cordova/mobile commands |
**Commands:** `meteor create`, `run`, `build`, `deploy`, `add/remove`, `mongo`, `shell`
## Isobuild (`tools/isobuild/`)
| File | Description |
|------|-------------|
| `bundler.js` | High-level bundling orchestration |
| `compiler.js` | Package compilation |
| `linker.js` | Module wrapping and linking |
| `import-scanner.ts` | Import statement parsing |
| `compiler-plugin.js` | Compiler plugin API |
| `isopack.js` | Package format handling |
## Runners (`tools/runners/`)
| File | Description |
|------|-------------|
| `run-app.js` | Web application runner |
| `run-mongo.js` | MongoDB server runner |
| `run-hmr.js` | Hot module reload runner |
| `run-all.js` | Multi-runner orchestration |
## Build Targets
| Target | Description |
|--------|-------------|
| `web.browser` | Modern browsers |
| `web.browser.legacy` | Legacy browsers (IE11) |
| `web.cordova` | Cordova mobile apps |
| `server` | Node.js server |
## Package Relationships
- `tools-core` → rspack, future integrations
- `accounts-base` → all accounts-* packages
- `ddp-server` + `ddp-client` → realtime communication
- `mongo` → minimongo (client-side)
- `webapp` → all HTTP handling
## Project Templates
Via `meteor create --<template>`: `react`, `vue`, `svelte`, `angular`, `blaze`, `typescript`, `tailwind`, `solid`, `apollo`, `minimal`, `bare`, `full`
## Environment Variables
| Variable | Purpose |
|----------|---------|
| `METEOR_PROFILE` | Build profiling |
| `METEOR_PACKAGE_DIRS` | Additional package paths |
| `METEOR_DEBUG_BUILD` | Verbose build output |
## Troubleshooting
- **Package not found:** Check `package.js` name, run `meteor reset`
- **Build plugin not running:** Check `archMatching`, file extensions
- **npm issues:** Clear `.meteor/local/`, run `meteor npm install`

188
.github/skills/conventions/SKILL.md vendored Normal file
View File

@@ -0,0 +1,188 @@
---
name: conventions
description: Use when writing new packages, adding CLI commands, creating build plugins, or following Meteor code patterns. Covers package.js structure, file naming, and common code patterns.
---
# Code Conventions
Package structure, file naming, and code patterns for the Meteor codebase.
## Package Structure
Every Meteor package follows this structure:
```
packages/my-package/
├── package.js # Package manifest (name, version, dependencies, exports)
├── my-package.js # Main implementation (or split by concern)
├── my-package-server.js # Server-only code (optional)
├── my-package-client.js # Client-only code (optional)
├── my-package-tests.js # Tests (loaded via api.addFiles in test mode)
└── README.md # Documentation (optional)
```
## Package.js Anatomy
```javascript
Package.describe({
name: 'my-package',
version: '1.0.0',
summary: 'Brief description',
git: 'https://github.com/meteor/meteor.git',
documentation: 'README.md'
});
Package.onUse(function(api) {
api.versionsFrom(['3.0']); // Minimum Meteor version
api.use([
'ecmascript', // ES2015+ support
'mongo', // MongoDB integration
'tracker' // Reactivity (client)
]);
api.use('accounts-base', { weak: true }); // Optional dependency
api.mainModule('my-package-server.js', 'server');
api.mainModule('my-package-client.js', 'client');
api.export('MyPackage'); // Global export
});
Package.onTest(function(api) {
api.use(['tinytest', 'my-package']);
api.addFiles('my-package-tests.js');
});
Npm.depends({
'lodash': '4.17.21' // npm dependencies
});
```
## File Naming Conventions
| Pattern | Purpose |
|---------|---------|
| `*-server.js` | Server-only code |
| `*-client.js` | Client-only code |
| `*-common.js` | Shared code |
| `*-tests.js` | Test files |
| `*.d.ts` | TypeScript declarations |
## Common Patterns
### Adding a New Core Package
1. Create directory in `/packages/my-package/`
2. Add `package.js` with proper dependencies
3. Implement functionality with proper exports
4. Add tests in `*-tests.js`
5. Update version numbers if needed
### Modifying Build System
Key files to understand:
- `/tools/isobuild/bundler.js` - High-level bundling
- `/tools/isobuild/compiler.js` - Package compilation
- `/tools/project-context.js` - Dependency resolution
- `/tools/cli/commands.js` - CLI command handlers
### Adding CLI Commands
Edit `/tools/cli/commands.js` or create new command file:
```javascript
main.registerCommand({
name: 'my-command',
options: {
'option-name': { type: String, short: 'o' }
},
catalogRefresh: new catalog.Refresh.Never()
}, function(options) {
// Implementation
});
```
### WebApp Middleware Pattern
```javascript
import { WebApp } from 'meteor/webapp';
// Add middleware before Meteor's default handlers
WebApp.rawConnectHandlers.use('/api', (req, res, next) => {
// Runs before authentication
next();
});
// Add middleware after authentication
WebApp.connectHandlers.use('/api', (req, res, next) => {
// req.userId available if authenticated
next();
});
```
### Build Plugin Pattern
```javascript
// In package.js
Package.registerBuildPlugin({
name: 'compile-my-files',
use: ['ecmascript', 'caching-compiler'],
sources: ['plugin.js'],
npmDependencies: { 'my-compiler': '1.0.0' }
});
// In plugin.js
Plugin.registerCompiler({
extensions: ['myext'],
archMatching: 'web'
}, () => new MyCompiler());
class MyCompiler extends CachingCompiler {
getCacheKey(inputFile) {
return inputFile.getSourceHash();
}
compileOneFile(inputFile) {
const source = inputFile.getContentsAsString();
const compiled = transform(source);
inputFile.addJavaScript({
data: compiled,
path: inputFile.getPathInPackage() + '.js'
});
}
}
```
### Using tools-core in Packages
```javascript
// In package.js
api.use('tools-core');
// In implementation
import {
logProgress,
checkNpmDependencyExists,
getMeteorAppConfig,
spawnProcess
} from 'meteor/tools-core';
// Check and install dependencies
if (!checkNpmDependencyExists('@rspack/core')) {
installNpmDependency(['@rspack/core@^1.7.1']);
}
// Spawn external process
const proc = spawnProcess('npx', ['rspack', 'build'], {
cwd: getMeteorAppDir(),
onStdout: (data) => logProgress(data)
});
```
## Version Patterns
Meteor uses `X.Y.Z-rcN.M` versioning where:
- `X.Y.Z` - Semantic version
- `rcN` - Release candidate number
- `M` - Package-specific revision

246
.github/skills/modern-tools/SKILL.md vendored Normal file
View File

@@ -0,0 +1,246 @@
---
name: modern-tools
description: Use when working with tools-core utilities, rspack integration, or modern tooling. Covers logging, npm management, process spawning, git helpers, and Meteor app configuration APIs.
---
# Modern Tools
Utility packages for modern tooling, bundler integrations, and native solutions.
## tools-core (`/packages/tools-core`)
Central utility package providing helpers for npm, logging, process management, and Meteor configuration. This is the foundation for modern tool integrations.
### Logging Module (`lib/log.js`)
```javascript
import { logProgress, logError, logInfo, logSuccess } from 'meteor/tools-core';
logProgress('Building application...'); // Blue
logSuccess('Build complete'); // Green
logError('Build failed'); // Red
logInfo('Using Rspack bundler'); // Purple
```
Respects `METEOR_DISABLE_COLORS` environment variable.
### NPM Management Module (`lib/npm.js`)
| Function | Description |
|----------|-------------|
| `getNodeBinaryPath(binaryName)` | Gets path to Node binaries (npm, npx, node) |
| `checkNpmDependencyExists(dep, opts)` | Checks if npm package is installed |
| `checkNpmBinaryExists(binary, opts)` | Checks if binary exists in node_modules/.bin |
| `checkNpmDependencyVersion(dep, opts)` | Validates semver with conditions (gte, lt, eq) |
| `installNpmDependency(deps, opts)` | Installs dependencies (npm/yarn, dev/exact flags) |
| `getNpmCommand(args)` | Returns npm command with `meteor npm` fallback |
| `getNpxCommand(args)` | Returns npx command with `meteor npx` fallback |
| `getYarnCommand(args)` | Gets yarn command path |
| `isYarnProject(opts)` | Detects yarn projects (yarn.lock, packageManager) |
| `getMonorepoPath(opts)` | Detects monorepo root (workspaces, lerna, pnpm) |
| `isMonorepo(opts)` | Boolean monorepo detection |
### Process Management Module (`lib/process.js`)
| Function | Description |
|----------|-------------|
| `spawnProcess(cmd, args, opts)` | Spawns process with streaming output, color preservation |
| `stopProcess(proc, opts)` | Graceful termination with SIGTERM/SIGKILL fallback |
| `isProcessRunning(proc)` | Checks if process is still running |
| `isPortAvailable(port, host)` | Checks if port is free |
| `waitForPort(port, opts)` | Waits for port availability with timeout |
Options for `spawnProcess`: `env`, `cwd`, `detached`, `onStdout`, `onStderr`, `onExit`, `onError`
### Meteor Configuration Module (`lib/meteor.js`)
**Application Configuration:**
| Function | Description |
|----------|-------------|
| `getMeteorAppDir()` | Gets application root directory |
| `getMeteorAppPackageJson()` | Parses app's package.json |
| `getMeteorAppConfig()` | Retrieves Meteor config from package.json or Plugin |
| `getMeteorAppPort()` | Gets app port from environment |
| `getMeteorAppConfigModern()` | Gets modern bundler configuration |
| `isMeteorAppConfigModernVerbose()` | Checks verbose flag |
| `hasMeteorAppConfigAutoInstallDeps()` | Auto-install deps flag |
**Entry Points:**
| Function | Description |
|----------|-------------|
| `getMeteorAppEntrypoints()` | Gets main/test modules for client/server |
| `getMeteorInitialAppEntrypoints()` | Gets initial entry points with HTML detection |
| `isMeteorAppTestModule()` | Checks if project is test module |
| `setMeteorAppEntrypoints(opts)` | Sets entry points via environment variables |
| `setMeteorAppIgnore(pattern)` | Sets file ignore patterns |
| `setMeteorAppCustomScriptUrl(url)` | Sets custom script URLs |
**Command Detection:**
| Function | Description |
|----------|-------------|
| `isMeteorAppRun()` | Running in 'run' mode |
| `isMeteorAppBuild()` | Running in 'build' or 'deploy' |
| `isMeteorAppUpdate()` | Running in 'update' |
| `isMeteorAppTest()` | In test mode |
| `isMeteorAppTestFullApp()` | Test mode with full-app flag |
| `isMeteorAppTestWatch()` | Test mode in watch mode |
| `isMeteorAppNativeAndroid()` | Native Android mode |
| `isMeteorAppNativeIos()` | Native iOS mode |
| `isMeteorAppNative()` | Any native mode |
| `isMeteorAppDevelopment()` | Development mode |
| `isMeteorAppProduction()` | Production mode |
| `isMeteorAppDebug()` | Debug mode |
**Package Detection:**
| Function | Description |
|----------|-------------|
| `isMeteorBlazeProject()` | Has blaze/blaze-html-templates |
| `isMeteorBlazeHotProject()` | Blaze with hot reload |
| `isMeteorCoffeescriptProject()` | Has CoffeeScript |
| `isMeteorLessProject()` | Has Less CSS |
| `isMeteorScssProject()` | Has SCSS/Sass |
| `isMeteorTypescriptProject()` | Has TypeScript |
| `isMeteorBundleVisualizerProject()` | Has bundle visualizer |
| `isMeteorPackagesTest()` | test-packages command |
**File Operations:**
| Function | Description |
|----------|-------------|
| `getMeteorAppFilesAndFolders(opts)` | Scans app directory (recursive, with ignore) |
| `getMeteorAppPackages()` | Lists all loaded packages |
| `getMeteorEnvPackageDirs()` | Gets package directories from env vars |
| `getMeteorToolsRequire(filePath)` | Requires module relative to Meteor tools |
### Global State Module (`lib/global-state.js`)
Maintains persistent state across file changes during development:
```javascript
import { getGlobalState, setGlobalState, removeGlobalState, clearGlobalState } from 'meteor/tools-core';
setGlobalState('buildStartTime', Date.now());
const startTime = getGlobalState('buildStartTime');
```
### Git Management Module (`lib/git.js`)
| Function | Description |
|----------|-------------|
| `isGitRepository(dir)` | Checks if directory is git repo |
| `gitignoreExists(dir)` | Checks .gitignore existence |
| `ensureGitignoreExists(dir, entries)` | Creates .gitignore with initial entries |
| `getMissingGitignoreEntries(dir, entries)` | Finds missing entries |
| `addGitignoreEntries(dir, entries, ctx)` | Adds entries with context logging |
### String Utilities (`lib/string.js`)
| Function | Description |
|----------|-------------|
| `capitalizeFirstLetter(str)` | Capitalizes first character |
| `shuffleString(str)` | Shuffles string characters |
| `joinWithAnd(items, opts)` | Human-readable list ("a, b, and c") |
---
## Rspack Integration (`/packages/rspack`)
Modern bundler integration using Rspack (Rust-based Webpack alternative).
### Package Structure
| File | Description |
|------|-------------|
| `lib/constants.js` | Default versions, global state keys, build contexts |
| `lib/dependencies.js` | Dependency checking and auto-installation |
| `lib/build-context.js` | Build directory management |
| `lib/config.js` | Meteor configuration for Rspack |
| `lib/processes.js` | Rspack process spawning |
| `lib/compilation.js` | Compilation tracking |
### Build Contexts
| Context | Directory | Purpose |
|---------|-----------|---------|
| `RSPACK_BUILD_CONTEXT` | `_build` | Build output |
| `RSPACK_ASSETS_CONTEXT` | `build-assets` | Static assets |
| `RSPACK_CHUNKS_CONTEXT` | `build-chunks` | Chunk bundles |
| `RSPACK_DOCTOR_CONTEXT` | `.rsdoctor` | Analysis/diagnostics |
### Key Dependencies
- `@rspack/core` ^1.7.1
- `@meteorjs/rspack` ^0.3.56 (configuration logic)
- `@rspack/plugin-react-refresh` ^1.4.3
- `swc-loader` ^0.2.6
### Integration with tools-core
- Uses `getMeteorInitialAppEntrypoints()` for entry points
- Uses command detection functions for build mode awareness
- Uses process spawning and npm utilities
---
## TypeScript Compiler (`/packages/typescript`)
Compiler plugin for TypeScript/TSX file compilation.
**Registered Plugin:** `compile-typescript`
**Supported Extensions:** `.ts`, `.tsx`
**Implied Packages:** `modules`, `ecmascript-runtime`, `babel-runtime`, `promise`, `dynamic-import`
**Features:**
- Transpiles TypeScript before Babel processing
- Supports client/server/legacy browser targets
- Integrates with React Fast Refresh for HMR
**Limitations:**
- Per-file transpilation (no cross-file type analysis)
- No tsconfig.json support (Meteor manages settings)
- No type checking during compilation
- No .d.ts generation
---
## WebApp & Express (`/packages/webapp`)
HTTP server integration using Express.js 5.x framework.
### Key APIs
```javascript
import { WebApp } from 'meteor/webapp';
// Middleware registration
WebApp.connectHandlers.use('/api', myMiddleware);
WebApp.handlers.use(compression());
// Direct Express access
WebApp.expressApp.get('/health', (req, res) => res.send('OK'));
// Server instance
WebApp.httpServer;
// Hooks
WebApp.onListening(() => console.log('Server ready'));
```
### Express Exports
| Property | Description |
|----------|-------------|
| `WebApp.connectHandlers` | Express middleware registry (legacy name) |
| `WebApp.handlers` | Current middleware registry |
| `WebApp.rawConnectHandlers` | Raw Express handlers |
| `WebApp.expressApp` | Direct Express app instance |
| `WebApp.httpServer` | HTTP server instance |
| `WebApp.express` | Express module export |
**Dependencies:** express@5.1.0, cookie-parser@1.4.6, compression@1.7.4, errorhandler@1.5.1

152
.github/skills/packages/SKILL.md vendored Normal file
View File

@@ -0,0 +1,152 @@
---
name: packages
description: Use when exploring the package ecosystem, finding which package handles a feature, understanding package relationships, or adding dependencies. Lists all core packages by domain.
---
# Core Packages
Overview of Meteor's package ecosystem organized by domain.
## Authentication & Accounts
| Package | Description |
|---------|-------------|
| `accounts-base` | Foundation for the user account system |
| `accounts-password` | Password-based authentication |
| `accounts-passwordless` | Magic-link/token-based authentication |
| `accounts-2fa` | Two-factor authentication support |
| `accounts-ui` / `accounts-ui-unstyled` | Pre-built UI components for auth |
| `accounts-oauth` | OAuth protocol support |
| `oauth` / `oauth1` / `oauth2` | OAuth implementation |
| `oauth-encryption` | Encrypted OAuth token storage |
| `service-configuration` | OAuth provider configuration |
**Social Login Providers:**
- `accounts-facebook`, `accounts-github`, `accounts-google`
- `accounts-twitter`, `accounts-meetup`, `accounts-weibo`
- `accounts-meteor-developer`
## Data & Database
| Package | Description |
|---------|-------------|
| `mongo` | MongoDB integration and collection API |
| `minimongo` | Client-side MongoDB emulation |
| `mongo-id` | MongoDB ObjectID generation |
| `mongo-livedata` | Reactive MongoDB queries |
| `npm-mongo` | MongoDB Node.js driver wrapper |
| `mongo-dev-server` | Development MongoDB server |
| `ddp` | Distributed Data Protocol meta-package |
| `ddp-common` | Shared DDP utilities |
| `ddp-client` | DDP client implementation |
| `ddp-server` | DDP server implementation |
| `ddp-rate-limiter` | Rate limiting for DDP methods/subscriptions |
| `ejson` | Extended JSON serialization |
## Build System & Compilation
| Package | Description |
|---------|-------------|
| `babel-compiler` | JavaScript transpilation via Babel |
| `babel-runtime` | Babel runtime helpers |
| `ecmascript` | ECMAScript 2015+ support |
| `ecmascript-runtime` | ES6+ runtime polyfills |
| `typescript` | TypeScript compilation support |
| `modules` | ES modules system |
| `modules-runtime` | Module runtime implementation |
| `modules-runtime-hot` | Hot module reloading runtime |
| `hot-code-push` | Live code updates |
| `hot-module-replacement` | HMR support |
| `rspack` | Rspack bundler integration |
| `boilerplate-generator` | HTML boilerplate generation |
| `dynamic-import` | Dynamic `import()` support |
| `caching-compiler` | Build cache management |
## Minification & Assets
| Package | Description |
|---------|-------------|
| `minifier-js` | JavaScript minification (terser) |
| `minifier-css` | CSS minification |
| `standard-minifier-js` | Default JS minifier package |
| `standard-minifier-css` | Default CSS minifier package |
| `standard-minifiers` | Meta-package for minifiers |
| `static-html` | Static HTML file processing |
## Web & Server
| Package | Description |
|---------|-------------|
| `webapp` | HTTP server and request handling |
| `webapp-hashing` | Asset fingerprinting |
| `reload` | Client-side app reload mechanism |
| `reload-safetybelt` | Reload failure recovery |
| `autoupdate` | Automatic client updates |
| `browser-policy` | Content Security Policy |
| `force-ssl` | HTTPS enforcement |
| `allow-deny` | Collection permission rules |
| `fetch` | HTTP Fetch API polyfill |
| `routepolicy` | Route-based policies |
## Client-Side Utilities
| Package | Description |
|---------|-------------|
| `tracker` | Reactive dependency tracking |
| `reactive-var` | Single reactive value |
| `reactive-dict` | Reactive key-value store |
| `session` | Client-side session storage |
| `localstorage` | LocalStorage wrapper |
| `socket-stream-client` | WebSocket client |
| `random` | Cryptographic random generation |
| `check` | Runtime type checking |
| `underscore` | Utility library |
| `base64` | Base64 encoding/decoding |
| `diff-sequence` | Array diffing algorithm |
| `id-map` | ID-based mapping |
| `ordered-dict` | Ordered dictionary |
## Testing (6 packages)
| Package | Description |
|---------|-------------|
| `tinytest` | Meteor's built-in test framework |
| `tinytest-harness` | Test harness utilities |
| `test-helpers` | Testing utility functions |
| `test-in-browser` | Browser-based test runner |
| `test-in-console` | Console-based test runner |
## Context & Roles
| Package | Description |
|---------|-------------|
| `context` | Request context management (AsyncLocalStorage) |
| `roles` | User roles and permissions system |
## Deprecated Packages (`packages/deprecated/`)
40+ legacy packages maintained for backward compatibility:
- UI libraries: `amplify`, `backbone`, `d3`, `handlebars`
- Legacy OAuth: `facebook`, `github`, `google` (use `accounts-*` instead)
- Config UIs: `*-config-ui` packages
- Others: `jquery-history`, `jshint`, `jsparse`, `deps` (use `tracker`)
## Development-Only Packages
| Package | Description |
|---------|-------------|
| `autopublish` | Auto-publish all collections (remove in production) |
| `insecure` | Allow all database writes (remove in production) |
## NPM Packages (`/npm-packages`)
Packages published to npm for external use:
| Package | npm Name | Description |
|---------|----------|-------------|
| `meteor-babel` | `@meteorjs/babel` | Babel wrapper for ES2015+ transpilation |
| `babel-preset-meteor` | `@meteorjs/babel-preset-meteor` | Babel preset with Meteor-specific transforms |
| `meteor-rspack` | `@meteorjs/rspack` | Rspack configuration builder |
| `meteor-promise` | `meteor-promise` | ES6 Promise with Fiber support |
| `meteor-node-stubs` | `meteor-node-stubs` | Node.js core module polyfills for browser |
| `eslint-plugin-meteor` | `eslint-plugin-meteor` | Meteor-specific ESLint rules |

144
.github/skills/testing/SKILL.md vendored Normal file
View File

@@ -0,0 +1,144 @@
---
name: testing
description: Use when writing tests, debugging test failures, running the test suite, or setting up test infrastructure. Covers self-test, package tests, and modern E2E tests.
---
# Testing
Test patterns, commands, and utilities for the Meteor codebase.
## Test Commands
```bash
# CLI self-tests
./meteor self-test # Run all CLI tests
./meteor self-test "test name" # Run specific test
./meteor self-test --list # List available tests
./meteor self-test --exclude "^[a-b]" # Exclude tests by regex
./meteor self-test --retries 0 # Skip retries in development
# Package tests (TinyTest — view results at http://localhost:3000)
./meteor test-packages # Test all core packages
./meteor test-packages mongo # Test specific package
TINYTEST_FILTER="collection" ./meteor test-packages # Filter specific tests
# Package tests in console (headless via Puppeteer)
PUPPETEER_DOWNLOAD_PATH=~/.npm/chromium ./packages/test-in-console/run.sh
# Modern E2E tests (Jest + Playwright)
npm run install:modern # Install dependencies
npm run test:modern # Run all E2E tests
npm run test:modern -- -t="React" # Run specific test
```
## Modern E2E Tests (`tools/modern-tests/`)
Jest + Playwright suite for verifying modern bundler integrations (rspack). Tests cover framework skeletons and build scenarios.
**Test apps:** `apps/{react,vue,svelte,solid,blaze,typescript,babel,coffeescript,monorepo}`
## Test Helpers Package (`packages/test-helpers`)
Comprehensive testing utilities for Meteor applications.
### Async Testing
```javascript
import { testAsyncMulti, simplePoll, waitUntil } from 'meteor/test-helpers';
// Wait for condition
await waitUntil(() => someCondition, { timeout: 5000, interval: 100 });
// Poll until ready
simplePoll(() => isReady(), successCallback, failCallback);
```
### DOM/UI Testing
```javascript
import { clickElement, simulateEvent, canonicalizeHtml, renderToDiv } from 'meteor/test-helpers';
clickElement(button);
simulateEvent(input, 'keydown', { keyCode: 13 });
const normalized = canonicalizeHtml(html);
```
### Connection Testing
```javascript
import { makeTestConnection, captureConnectionMessages } from 'meteor/test-helpers';
const conn = makeTestConnection(clientId);
const messages = captureConnectionMessages(server);
```
### Utilities
| Function | Description |
|----------|-------------|
| `SeededRandom` | Predictable random for deterministic tests |
| `try_all_permutations()` | Test all permutations of inputs |
| `withCallbackLogger()` | Track callback invocations |
| `mockBehaviours()` | Behavior mocking |
## Tinytest (`packages/tinytest`)
Meteor's built-in test framework.
```javascript
Tinytest.add('my test', function (test) {
test.equal(1 + 1, 2);
test.isTrue(true);
test.throws(function () { throw new Error(); });
});
Tinytest.addAsync('async test', async function (test) {
const result = await asyncOperation();
test.equal(result, expected);
});
```
## Environment Variables
| Variable | Description |
|----------|-------------|
| `TEST_METADATA` | Test configuration JSON |
| `METEOR_TEST_PACKAGES` | Packages to test |
## Debug Commands
```bash
# Verbose build output
METEOR_DEBUG_BUILD=1 ./meteor run
# Profile build performance
METEOR_PROFILE=1 ./meteor build
# Force rebuild
./meteor reset && ./meteor run
# Debug Meteor tool with Chrome inspector
TOOL_NODE_FLAGS="--inspect-brk" ./meteor
```
## Writing Package Tests
In `package.js`:
```javascript
Package.onTest(function(api) {
api.use(['tinytest', 'test-helpers', 'my-package']);
api.addFiles('my-package-tests.js');
});
```
In `my-package-tests.js`:
```javascript
import { MyPackage } from 'meteor/my-package';
Tinytest.add('MyPackage - basic functionality', function (test) {
const result = MyPackage.doSomething();
test.equal(result, expected);
});
```

60
AGENTS.md Normal file
View File

@@ -0,0 +1,60 @@
# Meteor
Full-stack JavaScript platform for modern web and mobile applications.
## Commands
```bash
./meteor run # Run from source
./meteor create my-app # Create app
./meteor self-test # CLI tests
./meteor test-packages ./packages/<name> # Package tests
npm run test:modern # E2E tests (Jest + Playwright)
```
## Structure
```
packages/ # Core Meteor packages (~100+)
tools/ # CLI & build system (Isobuild)
npm-packages/ # Published @meteorjs/* packages
scripts/ # Build & release automation
```
## Key Entry Points
| Task | Location |
|------|----------|
| CLI commands | `tools/cli/commands.js` |
| Build system | `tools/isobuild/bundler.js` |
| Package lookup | `packages/<name>/package.js` |
| Modern bundler | `packages/rspack/`, `packages/tools-core/` |
## Skills
Load these for detailed context on specific topics:
| Skill | When to use |
|-------|-------------|
| [codebase](.github/skills/codebase/SKILL.md) | Build system, CLI, isobuild, tools/ directory |
| [conventions](.github/skills/conventions/SKILL.md) | Writing packages, CLI commands, code patterns |
| [testing](.github/skills/testing/SKILL.md) | Writing tests, debugging failures, test infrastructure |
| [packages](.github/skills/packages/SKILL.md) | Finding packages by feature, understanding dependencies |
| [modern-tools](.github/skills/modern-tools/SKILL.md) | tools-core utilities, rspack, modern integrations |
| [ai-context](.github/skills/ai-context/SKILL.md) | Creating, updating, or maintaining AI documentation files |
## Package Domains
| Category | Packages |
|----------|----------|
| Auth | `accounts-base`, `accounts-password`, `accounts-oauth` |
| Database | `mongo`, `minimongo`, `ddp-server`, `ddp-client` |
| Build | `babel-compiler`, `ecmascript`, `typescript`, `rspack` |
| Web | `webapp`, `autoupdate`, `reload` |
| Reactivity | `tracker`, `reactive-var`, `reactive-dict` |
## Notes
- `docs/` and `guide/` are the public documentation website, not agent context
- `v3-docs/` contains Meteor 3.x documentation
- See [DEVELOPMENT.md](DEVELOPMENT.md) for contributor setup

14
CLAUDE.md Normal file
View File

@@ -0,0 +1,14 @@
Read [AGENTS.md](AGENTS.md) before starting any task.
## Skills
Load these for detailed context on specific topics:
| Skill | When to use |
|-------|-------------|
| [codebase](.github/skills/codebase/SKILL.md) | Build system, CLI, isobuild, tools/ directory |
| [conventions](.github/skills/conventions/SKILL.md) | Writing packages, CLI commands, code patterns |
| [testing](.github/skills/testing/SKILL.md) | Writing tests, debugging failures, test infrastructure |
| [packages](.github/skills/packages/SKILL.md) | Finding packages by feature, understanding dependencies |
| [modern-tools](.github/skills/modern-tools/SKILL.md) | tools-core utilities, rspack, modern integrations |
| [ai-context](.github/skills/ai-context/SKILL.md) | Creating, updating, or maintaining AI documentation files |