Skip to content

Commit

Permalink
Docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@jayair
jayair committed Mar 13, 2024
1 parent e6ff54f commit c03a7a9
Show file tree
Hide file tree
Showing 3 changed files with 154 additions and 51 deletions.
89 changes: 67 additions & 22 deletions pkg/platform/src/config.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,7 @@
* app(input) {
* return {
* name: "my-sst-app",
* providers: {
* aws: {}
* }
* home: "aws"
* };
* },
* async run() {
Expand Down Expand Up @@ -85,53 +83,99 @@ export interface App {
*/
removal?: "remove" | "retain" | "retain-all";
/**
* The providers to use in this app and their config. SST supports all [Pulumi's providers](https://www.pulumi.com/registry/).
* The providers that are being used in this app. SST supports all [Pulumi's providers](https://www.pulumi.com/registry/). This allows you to use the components from these providers in your app.
*
* :::tip
* SST supports all Pulumi's providers.
* :::
* For example, if you use the [AWS Classic](https://www.pulumi.com/registry/packages/aws/) provider, you can use the `aws` components in your app.
*
* To add a new provider you need to:
* 1. Add the config for it in the `providers` object. The key is the name of the provider.
* 2. Install the provider using `sst install`.
* ```ts
* import * as aws from "@pulumi/aws";
*
* new aws.s3.BucketV2("b", {
* bucket: "mybucket"
* });
* ```
*
* :::note
* If you are using one of our quick starts with the `sst init` command, it'll automatically install the right provider for you.
* By default, your `home` provider is included in the `providers` list.
* :::
*
* You can check out the config of a provider over on Pulumi's docs. For example, here's the config for some common providers:
* - [AWS](https://www.pulumi.com/registry/packages/aws/api-docs/provider/#inputs)
* - [Cloudflare](https://www.pulumi.com/registry/packages/cloudflare/api-docs/provider/#inputs)
* If you don't set a `provider` it uses your `home` provider with the default config. So if you set `home` to `aws`, it's the same as doing:
*
* In most cases you don't need to pass in a config for the provider.
* ```ts
* {
* home: "aws",
* providers: {
* aws: true
* }
* }
* ```
*
* @default The `home` provider.
*
* @example
*
* Using the AWS provider. The credentials are handled by default by thw AWS SDK.
* You can also configure the provider props. Here's the config for some common providers:
* - [AWS](https://www.pulumi.com/registry/packages/aws/api-docs/provider/#inputs)
* - [Cloudflare](https://www.pulumi.com/registry/packages/cloudflare/api-docs/provider/#inputs)
*
* For example, to change the region for AWS.
*
* ```ts
* {
* providers: {
* aws: {}
* aws: {
* region: "us-west-2"
* }
* }
* }
* ```
*
* Adding the Cloudflare provider.
* You also add multiple providers.
*
* ```ts
* {
* providers: {
* aws: {},
* cloudflare: { }
* aws: true,
* cloudflare: true
* }
* }
* ```
*/
providers?: Record<string, any>;

/**
* Where to store all state for your app. This is where SST keeps track of deployed resources and secrets.
* The provider SST will use to store the state for your app. The state keeps track of all your resources and secrets. The state is generated locally and backed up in your cloud provider.
*
* :::tip
* SST uses the `home` provider to store the state for your app.
* :::
*
* Currently supports AWS and Cloudflare.
*
* Setting the `home` provider is the same as setting the `providers` list. So if you set `home` to `aws`, it's the same as doing:
*
* ```ts
* {
* home: "aws",
* providers: {
* aws: true
* }
* }
* ```
*
* If you want to confgiure your home provider, you can:
*
* ```ts
* {
* home: "aws",
* providers: {
* aws: {
* region: "us-west-2"
* }
* }
* }
* ```
*
*/
home: "aws" | "cloudflare";
}
Expand Down Expand Up @@ -159,8 +203,9 @@ export interface Config {
* app(input) {
* return {
* name: "my-sst-app",
* home: "aws",
* providers: {
* aws: {},
* aws: true,
* cloudflare: {
* accountId: "6fef9ed9089bb15de3e4198618385de2"
* }
Expand Down
26 changes: 19 additions & 7 deletions www/src/content/docs/docs/components.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Every SST app is made up of components. Components in turn create one or more pi

For example, `sst.aws.Function` lets you add a Lambda function to your app. While, `sst.aws.Nextjs` lets you deploy your Next.js app.

SST's components use [Pulumi](https://www.pulumi.com/docs/concepts/resources/components/) behind the scenes to create the low level infrastructure. These are generated from [Terraform modules](https://developer.hashicorp.com/terraform). SST allows you to customize the low level infrastructure.
SST's components use [Pulumi](https://www.pulumi.com/docs/concepts/resources/components/) behind the scenes to create the low level infrastructure. These are generated from [Terraform modules](https://developer.hashicorp.com/terraform). SST allows you to customize how these are created.

:::tip
You can create any type of infrastructure even if SST doesn't support it directly.
Expand All @@ -29,10 +29,22 @@ Components are classes that are name spaced under the cloud provider it deploys

These components are namespaced under `sst.cloudflare.*`. They use Pulumi's [Cloudflare](https://www.pulumi.com/registry/packages/cloudflare/) provider.

:::tip
SST supports all [Pulumi providers](https://www.pulumi.com/registry/).
:::

Aside from SST's components, you can use any [Pulumi provider](https://www.pulumi.com/registry/) for your Pulumi components in your app. You can read more about `providers` in [Config](/docs/reference/config/).

---

### Home

SST generates some state for your app and stores this in your `home` provider. This is used to keep track of the resources and secrets in your app.

Currently, SST supports AWS and Cloudflare as `home` providers. You can read more about the `home` provider in [Config](/docs/reference/config/).

---

## Constructor

To add a component to your app, you create an instance of it by passing in a couple of args. For example, here's the signature of the [Function](/docs/component/aws/function) component.
Expand Down Expand Up @@ -85,13 +97,13 @@ Args usually take primitive types. However, they also take a special version of

### Transform

Most components take the `transform` prop as a part of their constructor or methods. It's an object that takes callbacks that allow you to transform how that component's infrastructure is created.
Most components take a `transform` prop as a part of their constructor or methods. It's an object that takes callbacks that allow you to transform how that component's infrastructure is created.

For example, here's what's the `transform` prop looks like for the [Function](/docs/component/aws/function#transform) takes:

- `function`: A callback to transform the underlying Lambda function.
- `logGroup`: A callback to transform the Lambda's LogGroup resource.
- `role`: A callback to transform the role that the Lambda function assumes.
- `function`: A callback to transform the underlying Lambda function
- `logGroup`: A callback to transform the Lambda's LogGroup resource
- `role`: A callback to transform the role that the Lambda function assumes

The type for these callbacks is similar. Here's what the `role` callback looks like:

Expand Down Expand Up @@ -127,7 +139,7 @@ This allows you to either:
}
```

- Or, pass in a callback that takes the current `RoleArgs`, mutate it, and return `void`.
- Or, pass in a callback that takes the current `RoleArgs` and mutate it.

```ts
{
Expand Down Expand Up @@ -206,4 +218,4 @@ new sst.aws.Router("MyRouter", {
});
```

The way Input and Output types are connected together, allows SST to create dependencies between your components. This allows it to deploy your apps as fast as possible. You can learn more about [Input and Output types on the Pulumi docs](https://www.pulumi.com/docs/concepts/inputs-outputs/).
The way Input and Output types are connected together allows SST to create dependencies between your components. This allows it to deploy your apps as fast as possible. You can learn more about [Input and Output types on the Pulumi docs](https://www.pulumi.com/docs/concepts/inputs-outputs/).
90 changes: 68 additions & 22 deletions www/src/content/docs/docs/reference/config.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,7 @@ export default $config({
app(input) {
return {
name: "my-sst-app",
providers: {
aws: {}
}
home: "aws"
};
},
async run() {
Expand Down Expand Up @@ -64,7 +62,37 @@ The run function also has access to a list of [Global](/docs/reference/global/)
**Type** <code class="symbol">&ldquo;</code><code class="primitive">aws</code><code class="symbol">&rdquo;</code><code class="symbol"> | </code><code class="symbol">&ldquo;</code><code class="primitive">cloudflare</code><code class="symbol">&rdquo;</code>
</InlineSection>
</Section>
Where to store all state for your app. This is where SST keeps track of deployed resources and secrets.
The provider SST will use to store the state for your app. The state keeps track of all your resources and secrets. The state is generated locally and backed up in your cloud provider.

:::tip
SST uses the `home` provider to store the state for your app.
:::

Currently supports AWS and Cloudflare.

Setting the `home` provider is the same as setting the `providers` list. So if you set `home` to `aws`, it's the same as doing:

```ts
{
home: "aws",
providers: {
aws: true
}
}
```

If you want to confgiure your home provider, you can:

```ts
{
home: "aws",
providers: {
aws: {
region: "us-west-2"
}
}
}
```

</Segment>
### name
Expand Down Expand Up @@ -95,43 +123,60 @@ This means that you don't want to change the name of your app without removing t
**Type** <code class="primitive">Record</code><code class="symbol">&lt;</code><code class="primitive">string</code>, <code class="primitive">any</code><code class="symbol">&gt;</code>
</InlineSection>
</Section>
The providers to use in this app and their config. SST supports all [Pulumi's providers](https://www.pulumi.com/registry/).

:::tip
SST supports all Pulumi's providers.
:::
<InlineSection>
**Default** The `home` provider.
</InlineSection>
The providers that are being used in this app. SST supports all [Pulumi's providers](https://www.pulumi.com/registry/). This allows you to use the components from these providers in your app.

To add a new provider you need to:
1. Add the config for it in the `providers` object. The key is the name of the provider.
2. Install the provider using `sst install`.
For example, if you use the [AWS Classic](https://www.pulumi.com/registry/packages/aws/) provider, you can use the `aws` components in your app.

:::tip
If you are using one of our quick starts with the `sst init` command, it'll automatically install the right provider for you.
```ts
import * as aws from "@pulumi/aws";

new aws.s3.BucketV2("b", {
bucket: "mybucket"
});
```

:::note
By default, your `home` provider is included in the `providers` list.
:::

You can check out the config of a provider over on Pulumi's docs. For example, here's the config for some common providers:
If you don't set a `provider` it uses your `home` provider with the default config. So if you set `home` to `aws`, it's the same as doing:

```ts
{
home: "aws",
providers: {
aws: true
}
}
```

You can also configure the provider props. Here's the config for some common providers:
- [AWS](https://www.pulumi.com/registry/packages/aws/api-docs/provider/#inputs)
- [Cloudflare](https://www.pulumi.com/registry/packages/cloudflare/api-docs/provider/#inputs)

In most cases you don't need to pass in a config for the provider.

Using the AWS provider. The credentials are handled by default by thw AWS SDK.
For example, to change the region for AWS.

```ts
{
providers: {
aws: {}
aws: {
region: "us-west-2"
}
}
}
```

Adding the Cloudflare provider.
You also add multiple providers.

```ts
{
providers: {
aws: {},
cloudflare: { }
aws: true,
cloudflare: true
}
}
```
Expand Down Expand Up @@ -206,8 +251,9 @@ The `app` function is evaluated when your app loads.
app(input) {
return {
name: "my-sst-app",
home: "aws",
providers: {
aws: {},
aws: true,
cloudflare: {
accountId: "6fef9ed9089bb15de3e4198618385de2"
}
Expand Down

0 comments on commit c03a7a9

Please sign in to comment.