

# Droplet

The `Droplet` is a service container that gives you access to many of Vapor's facilities. It is responsible for registering routes, starting the server, appending middleware, and more.

Tip

Normally applications will only have one Droplet. However, for advanced use cases, it is possible to create more than one.

## Initialization

As you have probably already seen, the only thing required to create an instance of `Droplet` is to import Vapor.

    import Vapor

    let drop = try Droplet()

    // your magic here

    try drop.run()

Creation of the `Droplet` normally happens in the `main.swift` file.

Note

For the sake of simplicity, most of the documentations sample code uses just the `main.swift` file. You can read more about packages and modules in the Swift Package Manager conceptual overview.

## Environment

The `environment` is accessible via the config of the droplet. It contains the current environment your application is running in. Usually development, testing, or production.

    if drop.config.environment == .production {
        ...
    }

The environment affects Config and Logging. The environment is `development` by default. To change it, pass the `--env=` flag as an argument.

    vapor run serve --env=production

If you are in Xcode, you can pass arguments through the scheme editor.

Warning

Debug logs can reduce the number of requests your application can handle per second. Enable production mode to silence non-critical logs.

## Config Directory

The `workDir` property contains a path to the current working directory of the application. Vapor uses this property to find the folders related to your project, such as `Resources`, `Public`, and `Config`.

    print(drop.config.workDir) // /var/www/my-project/

Vapor automatically determines the working directory in most situations. However, you may need to manually set it for advanced use cases.

You can override the working directory through the `Droplet`'s initializer, or by passing the `--workdir` argument.

    vapor run serve --workdir="/var/www/my-project"

## Modifying Properties

The `Droplet`'s properties can be changed programmatically or through configuration.

### Programmatic

Properties on the `Droplet` are constant and can be overridden through the init method.

    let drop = try Droplet(server: MyServerType.self)

Here the type of server the `Droplet` uses is changed to a custom type. When the `Droplet` is run, this custom server type will be booted instead of the default server.

Warning

Using the init method manually can override configured properties.

### Configurable

If you want to modify a property of the `Droplet` only in certain cases, you can use `addConfigurable`. Say for example you want to email error logs to yourself in production, but you don't want to spam your inbox while developing.

    let config = try Config()
    config.addConfigurable(log: MyEmailLogger.init, name: "email")

    let drop = Droplet(config)

The `Droplet` will continue to use the default logger until you modify the `Config/droplet.json` file to point to your email logger. If this is done in `Config/production/droplet.json`, then your logger will only be used in production.

    {
        "log": "email"
    }

#### Supported Properties

Property | Type | `droplet.json` key | Config Initializable
--- | --- | --- | ---
server | ServerProtocol.Type | server | no
client | ClientProtocol.Type | client | no
log | LogProtocol | log | yes
hash | HashProtocol | hash | yes
cipher | CipherProtocol | cipher | yes
middleware | Middleware | middleware.[server,client] | no
console | ConsoleProtocol | console | yes
cache | CacheProtocol | cache | yes

#### Example

Let's create a custom logger to demonstrate Vapor's configurable properties.

`AllCapsLogger.swift`

    final class AllCapsLogger: LogProtocol {
        var enabled: [LogLevel] = []
        func log(_ level: LogLevel, message: String, file: String, function: String, line: Int) {
            print(message.uppercased() + "!!!")
        }
    }

    extension AllCapsLogger: ConfigInitializable {
        convenience init(config: Config) throws {
            self.init()
        }
    }

Now add the logger to the Droplet using the `addConfigurable` method for logs.

`main.swift`

    let config = try Config()
    config.addConfigurable(log: AllCapsLogger.init, name: "all-caps")

    let drop = try Droplet(config)

Whenever the `"log"` property is set to `"all-caps"` in the `droplet.json`, our new logger will be used.

`Config/development/droplet.json`

    {
        "log": "all-caps"
    }

Here we are setting our logger only in the `development` environment. All other environments will use Vapor's default logger.

#### Config Initializable

For an added layer of convenience, you can allow your custom types to be initialized from configuration files.

In our previous example, we initialized an `AllCapsLogger` before adding it to the Droplet.

Let's say we want to allow our project to configure how many exclamation points get added with each log message.

`AllCapsLogger.swift`

    final class AllCapsLogger: LogProtocol {
        var enabled: [LogLevel] = []
        let exclamationCount: Int

        init(exclamationCount: Int) {
            self.exclamationCount = exclamationCount
        }

        func log(_ level: LogLevel, message: String, file: String, function: String, line: Int) {
            print(message.uppercased() + String(repeating: "!", count: exclamationCount))
        }
    }

    extension AllCapsLogger: ConfigInitializable {
       convenience init(config: Config) throws {
            let count = config["allCaps", "exclamationCount"]?.int ?? 3
            self.init(exclamationCount: count)
       }
    }

Note

The first parameter to `config` is the name of the file.

Now that we have conformed our logger to `ConfigInitializable`, we can pass just the type name to `addConfigurable`.

`main.swift`

    let config = try Config()
    config.addConfigurable(log: AllCapsLogger.init, name: "all-caps")

    let drop = try Droplet(config)

Now if you add a file named `allCaps.json` to the `Config` folder, you can configure the logger.

`allCaps.json`

    {
        "exclamationCount": 5
    }

With this configurable abstraction, you can easily change how your application functions in different environments without needing to hard code these values into your source code.