# Lighting Web Runtime :: Server

The Lightning Web Runtime server is a pluggable application server.

An application is described using [configuration](#configuration) and enabled by the configured **services**.

[Addressable Services](../api/docs/classes/_services_addressable_service_.addressableservice.md) provide the basis for what LWC component dependencies can be supported by the application server.

## Getting Started

To install the core runtime package:

```
npm install @webruntime/server
```

## Startup script

The LWR Server API can be used to interact with a runnable app server. By default, the server, once created and started, will serve the application and components defined in the `webruntime-app.config.js`.

A simple startup script:

```
const { Server } = require('@webruntime/server');

const server = new Server();
server.initialize().then(() => {
    server.start();
});
```

## Project Setup

The project setup for a Lightning Web Application can be customized using the options in the `webruntime-app.config.js`.
However, the following is a recommendation for your project:

    .
    ├── dist                         # Build directory (buildDir) - containing static served content.
    ├── src
    │   ├── server                   # Runtime source code -- custom services, page resources, index.js
    │   ├── client                   # Client source code -- index.html, LWC components
    │   │   ├── modules              # Project source LWC components
    │   │   └── index.html           # Default application template
    └── webruntime-app.config.js     # Project Webruntime configuration
    └── package.json

## Configuration

Application configuration and customization is done via `webruntime-app.config.js`. Customization of what services the application requires, how the application components are bundled and provided to the client, and component compiler configuration can be set in `webruntime-app.config.js`.

A sample application configuration:

```javascript
/**
 * Sample App Configuration
 */

const { ComponentService, ImportMapService, AppBootstrapService } = require('@webruntime/services');

module.exports = {
    buildDir: 'dist',
    moduleDir: 'src/client/modules',

    // LWR Application configuration
    app: {
        defaultComponent: 'my/app',
        defaultTemplate: 'src/index.html',
    },

    // Addressable Services
    services: [ComponentService, ImportMapService, AppBootstrapService],

    // Component Bundling Configuration
    bundle: ['my/app'],

    // Registry of application bundle components, including shared lwc components
    // These specifiers are automatically included in the externals array below
    preloadModules: ['wire-service'],

    // These libraries will not be included in the page bundles
    externals: ['lwc', 'universal_container/loader'],
};
```

Additional details on [`Configuration Options`](../api/docs/modules/_config_.md)

## App Level Enhancements

Since the Runtime, encapsulates the application server hosting the application and its resource API's, it is possible to enhance and extend the underlying application by creating a server Extension.

You can use the extension to hook in additional services or API's to application server through either the [`extendApp`](docs/modules/_server_extensions_.md#ContainerAppExtension) or [`bootstrap`](docs/modules/_server_extensions_.md#ContainerBootstrapExtension) hooks.

It's recommended that your put your project-level server extensions alongside the other Runtime source code.

    .
    ├── src
    │   ├── server
    │   │   ├── extension.js        # Project server extension

### Configuration

The extensions are configured as a part of the `webruntime-app.config.js`.

```
module.exports = {
    ...
    server: {
        extensions: ["src/server/extensions.js"]
    }
}
```

### Usage Example

As one example of an extension, you can add your private APIs to the application server:

```
module.exports = {
    extendApp: ({ app, options }) => {
        app.use("/private/api", (req, res) => {
            res.send("Private .... shhhh");
        })
    }
}

```