Skip to content

Commit

Permalink
docs: Explain how to use AppRunner to start a server instance
Browse files Browse the repository at this point in the history
  • Loading branch information
joachimvh committed Dec 14, 2023
1 parent 3b28199 commit 1aee349
Showing 1 changed file with 56 additions and 1 deletion.
57 changes: 56 additions & 1 deletion documentation/markdown/usage/dev-configuration.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,61 @@
# Configuring the CSS as a development server in another project

It can be useful to use the CSS as local server to develop Solid applications against.
There are several ways to configure and run a server in your project.

## Starting the server through code

You can create a server instance in your code, or tests, by calling the `create` function of a new `AppRunner` instance.
The resulting object has `start` and `stop` functions.
The `create` function takes as input an object with 5 optional parameters
which can all be used to define the server configuration.
None of these are mandatory, if you don't think you need one you can probably ignore it.
These are discussed below.

### loaderProperties

These values are specifically to configure how Components.js handles starting the server.
Most of these are generally not going to be relevant,
but here are some of those you might want to change:

* **mainModulePath**: Determines where Components.js will look for components.
Defaults to the folder where the server dependency is installed.
In case you are making a custom component,
this value needs to point to the directory of your project instead.
* **logLevel**: The logging level of Components.js when building. Defaults to `warn`.

### config

The file path of the Components.js configuration that needs to be used.
This can also be an array of configuration paths.
The `@css:` prefix can be used for file paths to generate a path
relative to the folder where the server dependency is installed.
Defaults to `@css:config/default.json`.

### variableBindings

Allows you to assign values to the variables that are used in a Components.js configuration.
For example, `{ 'urn:solid-server:default:variable:port': 3000 }` tells the server to use port 3000.

### shorthand

Allows you to assign values to parameters similarly as if you would call the server from the CLI.
For example, `{ port: 3000 }` tells the server to use port 3000.

This is very similar to the `variableBindings` field mentioned above,
as CLI parameters all get translated into Components.js variables,
although some get transformed before being put into a variable.
If you are not sure which one to use, `shorthand` is the safer choice to use.

### argv

If used, this parameter expects a string array.
Here you can provide the raw dump of CLI values,
so you don't have to parse them yourself,
should this be useful for your application.

## Configuring the server in `package.json`

As an alternative to using CLI arguments, or environment variables, the CSS can be configured in the `package.json` as follows:

```json
Expand All @@ -24,7 +79,7 @@ As an alternative to using CLI arguments, or environment variables, the CSS can
```

These parameters will then be used when the `community-solid-server`
command is executed as an npm script (as shown in the example above).
command is executed as an `npm` script (as shown in the example above).
Or whenever the `community-solid-server` command is executed in the same
folder as the `package.json`.

Expand Down

0 comments on commit 1aee349

Please sign in to comment.