Merge branch 'main' of github.com:platformatic/docs

docs/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).
 
-:::
+:::

docs/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.
 
 :::
 

docs/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 />

docs/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 />

docs/packages/next/configuration.md

@@ -0,0 +1,33 @@
+import Issues from '../../getting-started/issues.md';
+
+# Configuration
+
+Platformatic Next 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 Next 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 />

docs/packages/next/overview.md

@@ -0,0 +1,45 @@
+---
+title: Overview
+label: Astro
+---
+
+import Issues from '../../getting-started/issues.md';
+
+# Platformatic Next
+
+The Platformatic Next allows to run a [Next](https://nextjs.org/) application as a Platformatic Runtime service with no modifications.
+
+## Getting Started
+
+Create or copy an Next 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/next/2.0.0.json",
+  "application": {
+    "basePath": "/frontend"
+  }
+}
+```
+
+## Architecture
+
+When starting Next.js in development mode, production mode or by using the `commands` property, Platformatic will choose a random port for the HTTP server and it will override any user or application setting.
+
+## 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 />

docs/packages/node/configuration.md

@@ -0,0 +1,40 @@
+import Issues from '../../getting-started/issues.md';
+
+# Configuration
+
+Platformatic Node 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 directly executing the service entrypoint. 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.
+
+## `node`
+
+Configures Node. Supported object properties:
+
+- **`main`**: The entrypoint of the application. This is only needed if the `main` property is not set in the service `package.json` file.
+- **`absoluteUrl`**: If set to `true`, then the service will receive the full URL from a Platformatic Composer. The default is `false`.
+
+## `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 />

docs/packages/node/overview.md

@@ -0,0 +1,92 @@
+---
+title: Overview
+label: Astro
+---
+
+import Issues from '../../getting-started/issues.md';
+
+# Platformatic Node
+
+The Platformatic Node allows to run a [Fastify](https://fastify.io/), [Express](https://expressjs.com/), [Koa](https://koajs.com/#) or plain Node application as a Platformatic Runtime service with no modifications.
+
+## Getting Started
+
+Create or copy your 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/node/2.0.0.json",
+  "application": {
+    "basePath": "/frontend"
+  }
+}
+```
+
+## Architecture
+
+If your server entrypoint exports a `create` or `build` function, then Platformatic Node will execute it and then will wait for it to return a server object. In this situation the server will be used without starting a TCP server. The TCP server is started if the service is the runtime entrypoint.
+
+If your server entrypoint does not export a function, then Platformatic runtime will execute the function and wait for a TCP server to be started.
+
+In both cases, the listening port is always modified and chosen randomly, overriding any user or application setting.
+
+If the service uses the `commands` property then it's always responsible to start a HTTP server and the `create` or `build` functions are not supported anymore.
+
+In all cases, Platformatic runtime will modify the server port replacing it with a random port and then it will integrate the external service in the runtime.
+
+## Example services entrypoints
+
+### Fastify with build function
+
+```js
+import fastify from 'fastify'
+
+export function create() {
+  const app = fastify({
+    logger: { level: globalThis.platformatic?.logLevel ?? 'info' }
+  })
+
+  const prefix = globalThis.platformatic?.basePath ?? ''
+
+  app.get(`${prefix}/env`, async () => {
+    return { production: process.env.NODE_ENV === 'production' }
+  })
+
+  return app
+}
+```
+
+### Express with no build function
+
+```js
+import express from 'express'
+
+const app = express()
+
+const prefix = globalThis.platformatic?.basePath ?? ''
+
+app.get(`${prefix}/env`, (req, res) => {
+  res.send({ production: process.env.NODE_ENV === 'production' })
+})
+
+app.listen(3000)
+```
+
+## 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 />
+````

docs/packages/remix/configuration.md

@@ -0,0 +1,16 @@
+import Issues from '../../getting-started/issues.md';
+
+# Configuration
+
+Platformatic Remix is configured with a configuration file. It supports the use
+of environment variables as setting values with [configuration placeholders](#configuration-placeholders).
+
+It supports all the [settings supported by Platformatic Vite](../vite/configuration.md), plus the following one:
+
+- **`remix.outputDirectory`**: The subdirectory where production build is stored at when using `wattpm build` or `plt build`. The default is `build`.
+
+:::note
+Platformatic Remix uses this property instead of `application.outputDirectory` (which is ignored).
+:::
+
+<Issues />