From 36ba2701774109b681a7281208a2edc7198acf61 Mon Sep 17 00:00:00 2001 From: Frederico Maia Date: Mon, 24 Mar 2025 19:22:03 -0300 Subject: [PATCH 1/3] Enhance CLI documentation for `meteor help`, `meteor run`, and `meteor deploy` commands. --- v3-docs/docs/cli/index.md | 354 ++++++++++++++++++++++++-------------- 1 file changed, 225 insertions(+), 129 deletions(-) diff --git a/v3-docs/docs/cli/index.md b/v3-docs/docs/cli/index.md index 8cdcb64636..92cbe6acb5 100644 --- a/v3-docs/docs/cli/index.md +++ b/v3-docs/docs/cli/index.md @@ -8,76 +8,154 @@ command-line tool. This is just an overview and does not mention every command or every option to every command; for more details, use the `meteor help` command. -## meteor help {meteorhelp} +## meteor help {#meteorhelp} -Get help on meteor command line usage. Running `meteor help` by -itself will list the common meteor -commands. Running meteor help command will print -detailed help about the command. +Get help on meteor command line usage. +```bash +meteor help +``` -## meteor run {meteorrun} +Lists the common meteor commands. -Run a meteor development server in the current project. Searches -upward from the current directory for the root directory of a Meteor -project. Whenever you change any of the application's source files, the -changes are automatically detected and applied to the running -application. +```bash +meteor help +``` -You can use the application by pointing your web browser at -localhost:3000. No Internet connection is -required. +Prints detailed help about the specific command. -This is the default command. Simply running `meteor` is the -same as `meteor run`. +## meteor run {#meteorrun} -To pass additional options to Node.js use the `SERVER_NODE_OPTIONS` environment variable. E.g. for Windows PowerShell: -`$env:SERVER_NODE_OPTIONS = '--inspect' | meteor run`. Or for Linux: `SERVER_NODE_OPTIONS=--inspect-brk meteor run`. +Run a meteor development server in the current project. -To specify a port to listen on (instead of the default 3000), use `--port [PORT]`. -(The development server also uses port `N+1` for the default MongoDB instance) +```bash +meteor run +``` -For example: `meteor run --port 4000` -will run the development server on `http://localhost:4000` -and the development MongoDB instance on `mongodb://localhost:4001`. +::: tip +This is the default command. Simply running `meteor` is the same as `meteor run`. +::: -Run `meteor help run` to see the full list of options. +### Features -## meteor debug {meteordebug} +- Automatically detects and applies changes to your application's source files +- No Internet connection required +- Accesses the application at [localhost:3000](http://localhost:3000) by default +- Searches upward from the current directory for the root directory of a Meteor project -Run the project, but suspend the server process for debugging. +### Options -> **NOTE:** The `meteor debug` command has been superseded by the more flexible -> `--inspect` and `--inspect-brk` command-line flags, which work for any `run`, -> `test`, or `test-packages` command. -> -> The syntax of these flags is the same as the equivalent Node.js -> [flags](https://nodejs.org/en/docs/inspector/#command-line-options), -> with two notable differences: -> -> * The flags affect the server process spawned by the build process, -> rather than affecting the build process itself. -> -> * The `--inspect-brk` flag causes the server process to pause just after -> server code has loaded but before it begins to execute, giving the -> developer a chance to set breakpoints in server code. +| Option | Description | +|--------|-------------| +| `--port`, `-p ` | Port to listen on (default: 3000). Also uses port N+1 and a port specified by --app-port. Specify as --port=host:port to bind to a specific interface | +| `--open`, `-o` | Opens a browser window when the app starts | +| `--inspect[-brk][=]` | Enable server-side debugging via debugging clients. With --inspect-brk, pauses at startup (default port: 9229) | +| `--mobile-server ` | Location where mobile builds connect (defaults to local IP and port). Can include URL scheme (e.g., https://example.com:443) | +| `--cordova-server-port ` | Local port where Cordova will serve content | +| `--production` | Simulate production mode. Minify and bundle CSS and JS files | +| `--raw-logs` | Run without parsing logs from stdout and stderr | +| `--settings`, `-s ` | Set optional data for Meteor.settings on the server | +| `--release ` | Specify the release of Meteor to use | +| `--verbose` | Print all output from builds logs | +| `--no-lint` | Don't run linters used by the app on every rebuild | +| `--no-release-check` | Don't run the release updater to check for new releases | +| `--allow-incompatible-update` | Allow packages to be upgraded or downgraded to potentially incompatible versions | +| `--extra-packages ` | Run with additional packages (comma separated, e.g., "package-name1, package-name2@1.2.3") | +| `--exclude-archs ` | Don't create bundles for certain web architectures (comma separated, e.g., "web.browser.legacy, web.cordova") | -The server process will be suspended just before the first statement of -server code that would normally execute. In order to continue execution of -server code, use either the web-based Node Inspector or the command-line -debugger (further instructions will be printed in the console). +### Node.js Options -Breakpoints can be set using the `debugger` keyword, or through the web UI of Node Inspector ("Sources" tab). +To pass additional options to Node.js, use the `SERVER_NODE_OPTIONS` environment variable: -The server process debugger will listen for incoming connections from -debugging clients, such as node-inspector, on port 5858 by default. To -specify a different port use the `--debug-port ` option. +**Windows PowerShell:** +```powershell +$env:SERVER_NODE_OPTIONS = '--inspect' | meteor run +``` -The same debugging functionality can be achieved by adding the `--debug-port ` -option to other `meteor` tool commands, such as `meteor run` and `meteor test-packages`. +**Linux/macOS:** +```bash +SERVER_NODE_OPTIONS=--inspect-brk meteor run +``` -> **Note:** Due to a [bug in `node-inspector`](https://github.com/node-inspector/node-inspector/issues/903), pushing "Enter" after a command on the Node Inspector Console will not successfully send the command to the server. If you require this functionality, please consider using Safari or `meteor shell` in order to interact with the server console until the `node-inspector` project [fixes the bug](https://github.com/node-inspector/node-inspector/pull/955). Alternatively, there is a hot-patch available [in this comment](https://github.com/meteor/meteor/issues/7991#issuecomment-266709459) on [#7991](https://github.com/meteor/meteor/issues/7991). +### Port Configuration Example +```bash +meteor run --port 4000 +``` + +This command: +- Runs the development server on `http://localhost:4000` +- Runs the development MongoDB instance on `mongodb://localhost:4001` + +::: info +The development server always uses port `N+1` for the default MongoDB instance, where `N` is the application port. +::: + +## meteor debug {#meteordebug} + +Run the project with the server process suspended for debugging. + +::: warning Deprecation Notice +The `meteor debug` command has been superseded by the more flexible `--inspect` and `--inspect-brk` command-line flags, which work with `run`, `test`, and `test-packages` commands. +::: + +### Modern Debugging Approach + +```bash +# Debug server with auto-attachment +meteor run --inspect + +# Debug server and pause at start +meteor run --inspect-brk +``` + +### Command Usage + +```bash +meteor debug [--debug-port ] +``` + +### How It Works + +- Server process suspends just before the first statement of server code execution +- Debugger listens for incoming connections on port 5858 by default +- Use `--debug-port ` to specify a different port + +### Setting Breakpoints + +- Use the [`debugger`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger) keyword in your code +- Set breakpoints through the debugging client's UI (e.g., in the "Sources" tab) + +### Debugging Clients + +You can use either: +- Web-based Node Inspector +- Command-line debugger + +::: details Node Inspector Console Bug +Due to a [bug in `node-inspector`](https://github.com/node-inspector/node-inspector/issues/903), pressing "Enter" after a command in the Node Inspector Console may not successfully send the command to the server. + +**Workarounds:** +- Use Safari browser +- Use `meteor shell` to interact with the server console +- Apply the hot-patch available in [this comment](https://github.com/meteor/meteor/issues/7991#issuecomment-266709459) +::: + +### Differences from Node.js Flags + +The Meteor `--inspect` and `--inspect-brk` flags work similarly to Node.js flags with two key differences: + +1. They affect the server process spawned by the build process, not the build process itself +2. The `--inspect-brk` flag pauses execution after server code has loaded but before it begins to execute + +### Alternative Approach + +The same debugging functionality can be achieved by adding the `--debug-port ` option to other Meteor commands: + +```bash +meteor run --debug-port 5858 +meteor test-packages --debug-port 5858 +``` ## meteor create _app-name_ {meteorcreate} @@ -306,7 +384,7 @@ It will generate the following code in ``/imports/api`` That will have the following code: -## collection.js {meteorgenerate-collection.js} +### collection.js {meteorgenerate-collection.js} ```js import { Mongo } from 'meteor/mongo'; @@ -316,7 +394,7 @@ export const CustomerCollection = new Mongo.Collection('customer'); -## methods.js {meteorgenerate-methods.js} +### methods.js {meteorgenerate-methods.js} ```js import { Meteor } from 'meteor/meteor'; @@ -352,7 +430,7 @@ Meteor.methods({ -## publication.js {meteorgenerate-publication.js} +### publication.js {meteorgenerate-publication.js} ```js import { Meteor } from 'meteor/meteor'; @@ -366,7 +444,7 @@ Meteor.publish('allCustomers', function publishCustomers() { -## index.js {meteorgenerate-index.js} +### index.js {meteorgenerate-index.js} ```js export * from './collection'; @@ -376,7 +454,7 @@ export * from './publications'; Also, there is the same version of these methods using TypeScript, that will be shown bellow. -## path option {meteorgenerate-path} +### path option {meteorgenerate-path} If you want to create in another path, you can use the ``--path`` option in order to select where to place this boilerplate. It will generate the model in that path. Note that is used TypeScript in this example. @@ -392,7 +470,7 @@ It will generate in ``server/admin`` the another-client code: ![Screenshot 2022-11-09 at 11 32 39](https://user-images.githubusercontent.com/70247653/200857560-a4874e4c-1078-4b7a-9381-4c6590d2f63b.png) -## collection.ts {meteorgenerate-collection.ts} +### collection.ts {meteorgenerate-collection.ts} ```typescript import { Mongo } from 'meteor/mongo'; @@ -406,7 +484,7 @@ export type AnotherCustomer = { export const AnotherCustomerCollection = new Mongo.Collection('another-customer'); ``` -## methods.ts {meteorgenerate-methods.ts} +### methods.ts {meteorgenerate-methods.ts} ```typescript import { Meteor } from 'meteor/meteor'; @@ -443,7 +521,7 @@ Meteor.methods({ -## publications.ts {meteorgenerate-publications.ts} +### publications.ts {meteorgenerate-publications.ts} ```typescript import { Meteor } from 'meteor/meteor'; @@ -456,7 +534,7 @@ Meteor.publish('allAnotherCustomers', function publishAnotherCustomers() { -## index.ts {meteorgenerate-index.ts} +### index.ts {meteorgenerate-index.ts} ```typescript export * from './collection'; @@ -467,7 +545,7 @@ export * from './publications'; --- -## Using the Wizard {meteorgenerate-wizard} +### Using the Wizard {meteorgenerate-wizard} If you run the following command: @@ -485,7 +563,7 @@ It will prompt the following questions. --- -## Using your own template {meteorgenerate-templating} +### Using your own template {meteorgenerate-templating} `--templatePath` @@ -500,7 +578,7 @@ meteor generate feed --templatePath=/scaffolds-ts You can use your own templates for scaffolding your specific workloads. To do that, you should pass in a template directory URL so that it can copy it with its changes. -## How to rename things? {meteorgenerate-template-rename} +### How to rename things? {meteorgenerate-template-rename} Out of the box is provided a few functions such as replacing ``$$name$$``, ``$$PascalName$$`` and ``$$camelName$$`` @@ -518,7 +596,7 @@ const transformName = (name) => { } ``` -## How to bring your own templates? {meteorgenerate-template-faq} +### How to bring your own templates? {meteorgenerate-template-faq} `--replaceFn` @@ -582,81 +660,99 @@ third-party service providers. Once you have your account you can log in and log out from the command line, and check your username with `meteor whoami`. -## meteor deploy _site_ {meteordeploy} +## meteor deploy _site_ {#meteordeploy} -Deploy the project in your current directory to -Galaxy. +Deploys the project in your current directory to [Galaxy](https://www.meteor.com/galaxy). -Use `--owner` to decide which organization or user account you'd like to deploy -a new app to if you are a member of more than one Galaxy-enabled account. +### Basic Deployment -You can deploy in debug mode by passing `--debug`. This -will leave your source code readable by your favorite in-browser -debugger, just like it is in local development mode. - - - -To delete an application you've deployed, specify -the `--delete` option along with the site. - - - -You can add information specific to a particular deployment of your application -by using the `--settings` option. The argument to `--settings` is a file -containing any JSON string. The object in your settings file will appear on the -server side of your application in [`Meteor.settings`](../api/meteor#Meteor-settings). - -Settings are persistent. When you redeploy your app, the old value will be -preserved unless you explicitly pass new settings using the `--settings` option. -To unset `Meteor.settings`, pass an empty settings file. - -::: warning -`free` and `mongo` options were introduced in Meteor 2.0 -::: - -You can run your app for free using the option `--free`. But, there are some limitations. The first one is that you cannot use a custom domain to run a free app. Your domain must contain a Meteor domain name (`.meteorapp.com` to US region, `.au.meteorapp.com` to Asia region, or `.eu.meteorapp.com` to Europe region). Second thing you must know is that your free apps have Cold Start enabled. Cold Start means that your app will stop if it has no connection for 10 minutes, and it will go automatically up when someone tries to connect to it. The third thing you must know is that free apps run on one, and just one, Tiny container. This is important to know, because Tiny containers are NOT meant to production environment, so even small apps can crash with a lot of connections. To keep your app on free, you always need to provide this option. - -With the option `--mongo` you can deploy your app without having to pay for a MongoDB provider. By providing this option, Galaxy will create a database for you in our shared cluster and inject the mongo URL on your settings. So with this, you don't even need to provide the settings file anymore (if your settings files just have the mongo URL of course). This is great to test apps, but it shouldn't be used in a production environment, as you will be running in a shared Cluster with limited space. The rules behind this option are: If it is the first deploy of the app, and you provided the option `--mongo`, after the deploy is finished you will receive your mongo URL on your console (you can also see your URL on Galaxy in your app's version). You can put that URL on your settings file if want to. If you try to do a second without the option `--mongo` and without providing a mongo URL on your settings, your deploy will fail as usual. If you provide the option `--mongo` and a mongo URL, the mongo URL on your settings file is the one that will be used by Galaxy to connect your app to a MongoDB. One last thing, you need to have at least one document in your database so Meteor is really going to instantiate it. Then you will be able to access it using any MongoDB client with the provided URI. - -Use the options `--mongo` and `--free` to easily deploy a free app already with a mongo database connected to it. - -::: warning -Free apps and MongoDB shared hosting: Meteor Software reserves the right to stop or remove applications we deem to be abusing the free plan offering at any time. Please be advised that the free plan offering is not recommended for production applications. The shared MongoDB cluster that comes configured with the free plan does not provide backups or restoration resources. -::: - -::: warning -If you want to connect to your free MongoDB shared cluster using your on settings make sure you include this option in your settings in the Mongo package configuration section: +```bash +meteor deploy your-app.meteorapp.com ``` -packages: { - mongo: { - options: { - tlsAllowInvalidCertificates: true, - }, - }, + +### Deployment Options + +| Option | Description | +|--------|-------------| +| `--delete`, `-D` | Permanently delete this deployment | +| `--debug` | Deploy in debug mode (don't minify, etc.) | +| `--settings`, `-s ` | Set optional data for Meteor.settings | +| `--free` | Deploy as a free app (with limitations) | +| `--mongo` | Create and connect to a free shared MongoDB database | +| `--plan ` | Set app plan: `professional`, `essentials`, or `free` | +| `--container-size ` | Set container size: `tiny`, `compact`, `standard`, `double`, `quad`, `octa`, or `dozen` | +| `--owner` | Specify organization or user account to deploy to | +| `--cache-build` | Reuse the build if the git commit hash is the same | +| `--allow-incompatible-update` | Allow packages to be upgraded or downgraded to potentially incompatible versions | +| `--deploy-polling-timeout ` | Time to wait for build/deploy (defaults to 15 minutes) | +| `--no-wait` | Exit after code upload instead of waiting for deploy to complete | + +### Free Deployment + +Deploy a free app with MongoDB using: + +```bash +meteor deploy your-app.meteorapp.com --free --mongo +``` + +::: tip Quick Start +The combination of `--free` and `--mongo` is the fastest way to deploy an app without any additional configuration. +::: + +#### Free App Limitations + +- **Domain**: Must use a Meteor domain (`.meteorapp.com`, `.au.meteorapp.com`, or `.eu.meteorapp.com`) +- **Cold Start**: App stops after 30 minutes of inactivity and restarts on next connection +- **Resources**: Limited to one Tiny container (not recommended for production use) + + +### MongoDB Options + +#### Shared MongoDB (Free) + +The `--mongo` option creates a database in Galaxy's shared cluster: + +- On first deploy, you'll receive your MongoDB URI in the console +- The URI is also visible in your app's version details in Galaxy +- You must create at least one document to fully instantiate the database +- The database can be accessed using any MongoDB client with the provided URI + +::: warning +Free shared MongoDB is not recommended for production applications. The shared cluster doesn't provide backups or restoration resources. +::: + +#### MongoDB Connection Settings + +When connecting to the free MongoDB shared cluster using your own settings, include: + +```json +{ + "packages": { + "mongo": { + "options": { + "tlsAllowInvalidCertificates": true + } + } + } } ``` -This is necessary as our database provider does not have certificates installed on every machine and we don't want to force apps to have this certificate. More about this option [here](../api/collections.html#mongo_connection_options_settings) + +::: details Why is this needed? +This is necessary because the database provider doesn't have certificates installed on every machine. More about this option [here](../api/collections.html#mongo_connection_options_settings). ::: +### Important Notes -You can change the app plan by providing argument `--plan` with one of the following values: professional, essentials, or free. Be aware that this argument overwrites the `--free` argument. +- Settings persist between deployments unless explicitly changed +- Your project should be a git repository (commit hash is used to track code changes) +- Free apps and MongoDB shared hosting are not recommended for production use +- Meteor Software reserves the right to stop or remove applications that abuse the free plan -::: warning -The `plan` option is available since Meteor 2.1. -::: - -Use `--cache-build` to keep the bundle in your temp folder after the deploy is finished, this is helpful when you want to deploy the same code to different environments. For example, a [background job](https://cloud-guide.meteor.com/background-jobs.html) app from the same code as the web app. - -Your project should be a git repository as the commit hash is going to be used to decide if your code is still the same or not in the next deploy. - -::: warning -The `cache-build` option is available since Meteor 1.11. -::: - -With the argument `--container-size` you can change your app's container size using the deploy command. The valid arguments are: `tiny`, `compact`, `standard`, `double`, `quad`, `octa`, and `dozen`. One more thing to note here is that the `--container-size` flag can only be used when the `--plan` option is already specified, otherwise using the `--container-size` option will throw an error with the message : `Error deploying application: Internal error`. To see more about the difference and prices of each one you can check [here](https://www.meteor.com/cloud#pricing-section). - -::: warning -The `--container-size` option is available since Meteor 2.4.1. +::: info Version Compatibility +- `--free` and `--mongo` options were introduced in Meteor 2.0 +- `--plan` option was introduced in Meteor 2.1 +- `--container-size` option was introduced in Meteor 2.4.1 +- `--cache-build` option is available since Meteor 1.11 ::: ## meteor update {meteorupdate} From 1aad471da2bd7a4205ddf6fcaa2cb8fd0119926b Mon Sep 17 00:00:00 2001 From: Frederico Maia Date: Mon, 24 Mar 2025 19:33:02 -0300 Subject: [PATCH 2/3] Add documentation for `meteor profile` command --- v3-docs/docs/cli/index.md | 60 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/v3-docs/docs/cli/index.md b/v3-docs/docs/cli/index.md index 92cbe6acb5..e97912fe06 100644 --- a/v3-docs/docs/cli/index.md +++ b/v3-docs/docs/cli/index.md @@ -157,6 +157,66 @@ meteor run --debug-port 5858 meteor test-packages --debug-port 5858 ``` +## meteor profile {#meteorprofile} + +Run a performance profile for your Meteor application to analyze build and bundling performance. + +```bash +meteor profile [...] +``` + +::: info Availability +This command is available from Meteor 3.2 and newer. +::: + +### Usage + +This command monitors the bundler process and tracks key performance metrics to help analyze build and bundling performance. + +### Options + +| Option | Description | +|--------|-------------| +| `--size` | Monitor both bundle runtime and size | +| `--size-only` | Monitor only the bundle size | + +::: info +All other options from `meteor run` are also supported (e.g., `--settings`, `--exclude-archs`). +::: + +### Environment Variables + +| Variable | Description | Default | +|----------|-------------|---------| +| `METEOR_IDLE_TIMEOUT=` | Set a timeout for profiling | 90 seconds | +| `METEOR_CLIENT_ENTRYPOINT=` | Set a custom client entrypoint | From package.json | +| `METEOR_SERVER_ENTRYPOINT=` | Set a custom server entrypoint | From package.json | +| `METEOR_LOG_DIR=` | Set a custom log directory | Default log directory | + +::: tip +The default timeout (90s) is usually enough for each build step to complete. If you encounter errors due to early exits, increase the `METEOR_IDLE_TIMEOUT` value. +::: + +### Example Usage + +```bash +# Basic profile +meteor profile + +# Monitor bundle size only +meteor profile --size-only + +# Profile with custom settings and timeout +METEOR_IDLE_TIMEOUT=120 meteor profile --settings settings.json + +# Profile with custom entrypoints +METEOR_CLIENT_ENTRYPOINT=client/main.js METEOR_SERVER_ENTRYPOINT=server/main.js meteor profile +``` + +::: details Customizing the Profiling Process +You can pass any option that works with `meteor run` to customize the profiling process. This allows you to profile your application under specific conditions that match your deployment environment. +::: + ## meteor create _app-name_ {meteorcreate} The command `meteor create app-name` is the default command for creating a new Meteor project. It creates a subdirectory From b55f1c311d707382e55a55edc499f827561f7871 Mon Sep 17 00:00:00 2001 From: Frederico Maia Date: Mon, 24 Mar 2025 19:45:24 -0300 Subject: [PATCH 3/3] Add configuration to ignore dead links for localhost in VitePress --- v3-docs/docs/.vitepress/config.mts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/v3-docs/docs/.vitepress/config.mts b/v3-docs/docs/.vitepress/config.mts index 28bcdf0478..e3f35daf4a 100644 --- a/v3-docs/docs/.vitepress/config.mts +++ b/v3-docs/docs/.vitepress/config.mts @@ -25,6 +25,9 @@ export default defineConfig({ sitemap: { hostname: "https://v3-docs.meteor.com", }, + ignoreDeadLinks: [ + /^http:\/\/localhost/ + ], themeConfig: { // https://vitepress.dev/reference/default-theme-config nav: [