[automated commit] Bump docs to versions 2.4.0, 1.53.3

versioned_docs/version-2.2.1/composer/configuration.md → versioned_docs/version-2.4.0/composer/configuration.md

@@ -2,29 +2,30 @@ import Issues from '../getting-started/issues.md';
 
 # Configuration
 
-Platformatic Composer can be configured with a [configuration file](#configuration-files) in the different file formats below. The Composer also supports use of environment variables as setting values with [environment variable placeholders](../composer/configuration.md#setting-and-using-env-placeholders). 
+Platformatic Composer can be configured with a [configuration file](#configuration-files) in the different file formats below. The Composer also supports use of environment variables as setting values with [environment variable placeholders](../composer/configuration.md#setting-and-using-env-placeholders).
 
 ## Configuration Files
 
 Platformatic will automatically detect and load configuration files found in the current working directory with the file names listed [here](../file-formats.md#configuration-files).
 
-To specify a configuration file manually, use the [`--config` option](../cli.md#composer) with any `platformatic composer` CLI command. 
+To specify a configuration file manually, use the [`--config` option](../cli.md#composer) with any `platformatic composer` CLI command.
 
 ## Supported File Formats
 
 For detailed information on supported file formats and extensions, visit our [Supported File Formats and Extensions](../file-formats.md#supported-file-formats) page
 
 ## Configuration Settings
 
-Configuration file settings are grouped as follows:  
+Configuration file settings are grouped as follows:
 
+- **`basePath`** **(required)**: Configures the [basePath](../service/configuration.md#basePath).
 - **`server`** **(required)**: Configures the [server settings](../service/configuration.md#server)
 - **`composer`**: Specific settings for Platformatic Composer, such as service management and API composition.
 - **`metrics`**: Monitors and records performance [metrics](../service/configuration.md#metrics).
 - **`plugins`**: Manages additional functionality through [plugins](../service/configuration.md#plugins).
 - **`telemetry`**: Handles [telemetry data reporting](../service/configuration.md#telemetry).
 - **`watch`**: Observes file changes for [dynamic updates](../service/configuration.md#watch).
-- **`clients`**: Configures [client-specific](../service/configuration.md#clients) settings. 
+- **`clients`**: Configures [client-specific](../service/configuration.md#clients) settings.
 
 Sensitive data within these settings should use [configuration placeholders](#configuration-placeholders) to ensure security.
 
@@ -33,24 +34,37 @@ Sensitive data within these settings should use [configuration placeholders](#co
 Configure `@platformatic/composer` specific settings such as `services` or `refreshTimeout`:
 
 - **`services`** (`array`, default: `[]`) — is an array of objects that defines
-the services managed by the composer. Each service object supports the following settings:
+  the services managed by the composer. Each service object supports the following settings:
 
-  - **`id`** (**required**, `string`) - A unique identifier for the service. Use a Platformatic Runtime service id if the service is executing inside [Platformatic Runtime context](../runtime/overview.md#platformatic-runtime-context). 
-  - **`origin`** (`string`) - A service origin. Skip this option if the service is executing inside [Platformatic Runtime context](../runtime/overview.md#platformatic-runtime-context). In this case, service `id` will be used instead of origin. 
-  - **`openapi`** (`object`) - The configuration file used to compose [OpenAPI](#openapi) specification. 
-  - **`graphql`** (`object`) - The configuration for the [GraphQL](#graphql) service. 
+  - **`id`** (**required**, `string`) - A unique identifier for the service. Use a Platformatic Runtime service id if the service is executing inside [Platformatic Runtime context](../runtime/overview.md#platformatic-runtime-context).
+  - **`origin`** (`string`) - A service origin. Skip this option if the service is executing inside [Platformatic Runtime context](../runtime/overview.md#platformatic-runtime-context). In this case, service `id` will be used instead of origin.
+  - **`openapi`** (`object`) - The configuration file used to compose [OpenAPI](#openapi) specification.
+  - **`graphql`** (`object`) - The configuration for the [GraphQL](#graphql) service.
   - **`proxy`** (`object` or `false`) - Service proxy configuration. If `false`, the service proxy is disabled.
-    - `prefix` (**required**, `string`) - Service proxy prefix. All service routes will be prefixed with this value.
+
+    - `prefix` (`string`) - Service proxy prefix. All service routes will be prefixed with this value.
+
+    :::note
+    If the prefix is not explictly set, the composer and the service will try to find the best prefix for the service.
+
+    First of all, if the application code used the `platformatic.setBasePath` (which is always available in each service),
+    then the value will become the service prefix.
+
+    The next attempt will be to let the service autodetect its own prefix by using the configuration (as the `basePath` setting for `@platformatic/service`)
+    or by autodetecting the prefix from the host application (like Next.js).
+
+    When none of the criteria above successfully lead to a prefix, the service ID is chosen as last fallback to ensure there are not routing conflicts.
+    :::
 
 - **`openapi`** (`object`) - See the Platformatic Service [openapi](../service/configuration.md#service) option for more details.
-- **`graphql`** (`object`) - Has the Platformatic Service [graphql](../service//configuration.md#service) options, plus 
-  
-  - **`addEntitiesResolvers`** (`boolean`) - Automatically add related entities on GraphQL types, following the services entities configuration. See [graphql-composer entities](https://github.com/platformatic/graphql-composer#composer-entities) for details. 
+- **`graphql`** (`object`) - Has the Platformatic Service [graphql](../service//configuration.md#service) options, plus
+
+  - **`addEntitiesResolvers`** (`boolean`) - Automatically add related entities on GraphQL types, following the services entities configuration. See [graphql-composer entities](https://github.com/platformatic/graphql-composer#composer-entities) for details.
   - **`defaultArgsAdapter`** (`function` or `string`) - The default `argsAdapter` function for the entities, for example for the platformatic db mapped entities queries.
 
   ```js
   graphql: {
-    defaultArgsAdapter: (partialResults) => ({ where: { id: { in: partialResults.map(r => r.id) } } })
+    defaultArgsAdapter: partialResults => ({ where: { id: { in: partialResults.map(r => r.id) } } })
   }
   ```
 
@@ -59,7 +73,9 @@ the services managed by the composer. Each service object supports the following
   ```json
   "defaultArgsAdapter": "where.id.in.$>#id"
   ```
+
   - **`onSubgraphError`** (`function`) - Hook called when an error occurs getting schema from a subgraph. The arguments are:
+
     - `error` (`error`) - The error message
     - `subgraphName` (`string`) - The erroring subgraph
 
@@ -74,14 +90,14 @@ the services managed by the composer. Each service object supports the following
 - **`url`** (`string`) - A path of the route that exposes the OpenAPI specification. If a service is a Platformatic Service or Platformatic DB, use `/documentation/json` as a value. Use this or `file` option to specify the OpenAPI specification.
 - **`file`** (`string`) - A path to the OpenAPI specification file. Use this or `url` option to specify the OpenAPI specification.
 - **`prefix`** (`string`) - A prefix for the OpenAPI specification. All service routes will be prefixed with this value.
-- **`config`** (`string`) - A path to the OpenAPI configuration file. This file is used to customize the [OpenAPI](#openapi-configuration)specification. 
+- **`config`** (`string`) - A path to the OpenAPI configuration file. This file is used to customize the [OpenAPI](#openapi-configuration)specification.
 
 ### OpenAPI Configuration
 
 The OpenAPI configuration file is a JSON file that is used to customize the OpenAPI specification. It supports the following options:
 
 - **`ignore`** (`boolean`) - If `true`, the route will be ignored by the composer.
-If you want to ignore a specific method, use the `ignore` option in the nested method object.
+  If you want to ignore a specific method, use the `ignore` option in the nested method object.
 
   ```json title="Example JSON object"
   {
@@ -99,7 +115,6 @@ If you want to ignore a specific method, use the `ignore` option in the nested m
 
 - **alias** (`string`) - Use it create an alias for the route path. Original route path will be ignored.
 
-
   ```json title="Example JSON object"
   {
     "paths": {
@@ -111,24 +126,24 @@ If you want to ignore a specific method, use the `ignore` option in the nested m
   ```
 
 - **`rename`** (`string`) - Use it to rename composed route response fields.
-Use json schema format to describe the response structure, this only for  `200` response. 
+  Use json schema format to describe the response structure, this only for `200` response.
 
   ```json title="Example JSON object"
   {
     "paths": {
       "/users": {
         "responses": {
-            "200": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "properties": {
-                  "id": { "rename": "user_id" },
-                  "name": { "rename": "first_name" }
-                }
+          "200": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": { "rename": "user_id" },
+                "name": { "rename": "first_name" }
               }
             }
           }
+        }
       }
     }
   }
@@ -196,7 +211,7 @@ Use json schema format to describe the response structure, this only for  `200`
   - **`resolver`** (`object`) - The resolver to retrieve a list of objects - should return a list - and should accept as an arguments a list of primary keys or foreign keys.
     - **`name`** (`string`, **required**) - The name of the resolver.
     - **`argsAdapter (partialResults)`** (`function` or `string`) - The function invoked with a subset of the result of the initial query, where `partialResults` is an array of the parent node. It should return an object to be used as argument for `resolver` query. Can be a function or a [metaline](https://github.com/platformatic/metaline) string.
-  **Default:** if missing, the `defaultArgsAdapter` function will be used; if that is missing too, a [generic one](lib/utils.js#L3) will be used.
+      **Default:** if missing, the `defaultArgsAdapter` function will be used; if that is missing too, a [generic one](lib/utils.js#L3) will be used.
     - **`partialResults`** (`function` or `string`) - The function to adapt the subset of the result to be passed to `argsAdapter` - usually is needed only on resolvers of `fkeys` and `many`. Can be a function or a [metaline](https://github.com/platformatic/metaline) string.
   - **`pkey`** (`string`, **required**) - The primary key field to identify the entity.
   - **`fkeys`** (`array of objects`) an array to describe the foreign keys of the entities, for example `fkeys: [{ type: 'Author', field: 'authorId' }]`.
@@ -217,9 +232,11 @@ Use json schema format to describe the response structure, this only for  `200`
 ## Configuration References
 
 ### `telemetry`
+
 Telemetry involves the collection and analysis of data generated by the operations of services. See our [telemetry documentation](../service/configuration.md#telemetry) for details on configuring telemetry for Platformatic Service.
 
 ### `watch`
+
 The `watch` functionality helps in monitoring file changes and dynamically updating services. Learn more at Platformatic Service [watch](../service/configuration.md#watch)
 
 ### `clients`
@@ -232,6 +249,6 @@ Environment variable placeholders are used to securely inject runtime configurat
 
 ### PLT_ROOT
 
-The [PLT_ROOT](../service/configuration.md#plt_root) variable is used to configure relative path and is set to the directory containing the Service configuration file. 
+The [PLT_ROOT](../service/configuration.md#plt_root) variable is used to configure relative path and is set to the directory containing the Service configuration file.
 
-<Issues />
+<Issues />

versioned_docs/version-2.2.1/db/configuration.md → versioned_docs/version-2.4.0/db/configuration.md

@@ -18,6 +18,7 @@ For detailed information on supported file formats and extensions, please visit
 
 Configuration file settings are grouped as follows:
 
+- **`basePath`** **(required)**: Configures the [basePath](../service/configuration.md#basePath).
 - **`server`** **(required)**: Configures the [server settings](../service/configuration.md#server)
 - **`composer`**: Specific settings for Platformatic Composer, such as service management and API composition.
 - **`metrics`**: Monitors and records performance [metrics](../service/configuration.md#metrics).

versioned_docs/version-2.2.1/getting-started/quick-start-guide.md → versioned_docs/version-2.4.0/getting-started/quick-start-guide.md

@@ -5,11 +5,11 @@ import NewApiProjectInstructions from './new-api-project-instructions.md';
 
 # Quick Start Guide
 
-Welcome to your first steps with [Platformatic DB](/docs/reference/db/introduction.md). This guide will help you set up and run your first API using Platformatic DB with [SQLite](https://www.sqlite.org/). By the end of this guide, you'll have a fully functional API ready to use.
+Welcome to your first steps with [Platformatic DB](/docs/db/overview.md). This guide will help you set up and run your first API using Platformatic DB with [SQLite](https://www.sqlite.org/). By the end of this guide, you'll have a fully functional API ready to use.
 
 :::note
 
-While this guide uses [SQLite](https://www.sqlite.org/), Platformatic DB also supports [PostgreSQL](https://www.postgresql.org/), [MySQL](https://www.mysql.com/), and [MariaDB](https://mariadb.org/). For more details on database compatibility, see the [Platformatic DB documentation](/docs/reference/db/introduction.md).
+While this guide uses [SQLite](https://www.sqlite.org/), Platformatic DB also supports [PostgreSQL](https://www.postgresql.org/), [MySQL](https://www.mysql.com/), and [MariaDB](https://mariadb.org/). For more details on database compatibility, see the [Platformatic DB documentation](/docs/db/overview.md#supported-databases).
 
 :::
 
@@ -273,4 +273,4 @@ query {
 
 For more advanced guides, refer to the [Platformatic learning hub](../learn/overview.md).
 
-:::
+:::

versioned_docs/version-2.2.1/getting-started/quick-start-watt.md → versioned_docs/version-2.4.0/getting-started/quick-start-watt.md

@@ -137,7 +137,7 @@ curl http://localhost:3042
 Inside `my-app`, let's create a new Platformatic Composer
 
 ```bash
-npx create-platformatic@2.0.0-alpha.23
+npx create-platformatic
 ```
 
 This will output:
@@ -178,7 +178,7 @@ Then, edit `web/composer/platformatic.json` to add the `node` app:
     "services": [{
       "id": "node",
       "proxy": {
-        "path": "/node"
+        "prefix": "/node"
       }
     }],
     "refreshTimeout": 1000
@@ -265,7 +265,7 @@ Finally, let's add `Next` to our composer:
     "services": [{
       "id": "node",
       "proxy": {
-        "path": "/node"
+        "prefix": "/node"
       }
     }, {
       "id": "next"
@@ -285,7 +285,7 @@ Then, you can test it by opening your browser at [`http://localhost:3042/next`](
 
 In this example, we are exposing the Next.js app at `/next` and the Node.js app at `/node`.
 You can change the paths to suit your needs. Make sure to alter the `basePath` in `web/next/watt.json`
-and the `path` in `web/composer/platformatic.json` accordingly.
+and the `prefix` in `web/composer/platformatic.json` accordingly.
 
 :::
 

versioned_docs/version-2.4.0/packages/astro/configuration.md

@@ -0,0 +1,33 @@
+import Issues from '../../getting-started/issues.md';
+
+# Configuration
+
+Platformatic Astro is configured with a configuration file. It supports the use
+of environment variables as setting values with [configuration placeholders](#configuration-placeholders).
+
+## `application`
+
+Supported object properties:
+
+- **`basePath`**: Service proxy base path when exposing this application in a [composer](../../composer/configuration.md) when setting the `proxy` property. If not specified, the service will be exposed on the service or a value specified in the service code via `platformatic.setBasePath()`.
+- **`outputDirectory`**: The subdirectory where production build is stored at when using `wattpm build` or `plt build`. The default is `dist`.
+- **`include`**: The paths to include when deploying the service. The default is `['dist']`.
+- **`commands`**: An object specifying the commands to manage the application instead of using the Astro defaults. Supported commands are:
+  - **`install`**: The command to execute to install the service dependencies. The default is `npm ci --omit-dev`.
+  - **`build`**: The command to execute to build the application.
+  - **`development`**: The command to execute to start the application in development mode.
+  - **`production`**: The command to execute to start the application in production mode.
+
+## `logger`
+
+Configures the logger, see the [logger configuration](https://www.fastify.io/docs/latest/Reference/Server/#logger) for more information.
+
+## `server`
+
+Configures the HTTP server, see the [runtime](../../runtime/configuration.md#server) documentation.
+
+## `watch`
+
+Manages watching of the service, see the [service](../../service/configuration.md#watch) documentation.
+
+<Issues />

versioned_docs/version-2.4.0/packages/astro/overview.md

@@ -0,0 +1,49 @@
+---
+title: Overview
+label: Astro
+---
+
+import Issues from '../../getting-started/issues.md';
+
+# Platformatic Astro
+
+The Platformatic Astro allows to run an [Astro](https://astro.build/) application as a Platformatic Runtime service with no modifications.
+
+## Getting Started
+
+Create or copy an Astro application inside the `web` or `services` folder. If you are not using [`autoload`](../../runtime/configuration.md#autoload), you also have to explictly add the new service.
+
+You are all set, you can now start your runtime as usual via `wattpm dev` or `plt start`.
+
+## Example configuration file
+
+```json
+{
+  "$schema": "https://schemas.platformatic.dev/@platformatic/astro/2.0.0.json",
+  "application": {
+    "basePath": "/frontend"
+  }
+}
+```
+
+## Architecture
+
+When running in development mode, the Astro Vite development server is run a in worker thread in the same process of the Platformatic runtime. The server port is chosen randomly and it will override any user setting.
+
+When running in production mode, a custom Fastify server will serve the static or dynamic (for SSR) application. The service is run a in worker thread in the same process of the Platformatic runtime and it will not start a TCP server unless it's the runtime entrypoint.
+
+In both modes if the service uses the `commands` property then it's responsible to start a HTTP server. The Platformatic runtime will modify the server port replacing it with a random port and then it will integrate the external service in the runtime.
+
+## Configuration
+
+See the [configuration](./configuration.md) page.
+
+## API
+
+- **`platformatic.setBasePath(path)`**: This function can be use to override the base path for the service. If not properly configure in the composer, this can make your application unaccessible.
+- **`platformatic.id`**: The id of the service.
+- **`platformatic.root`**: The root directory of the service.
+- **`platformatic.basePath`**: The base path of the service in the composer.
+- **`platformatic.logLevel`**: The log level configured for the service.
+
+<Issues />