Linking

Resource linking is a feature of SST that allows you to link resources together and access them in a typesafe and secure way.

1. Create a resource that you want to link to. For example, a bucket.

   const bucket = new sst.aws.Bucket("MyBucket");

2. Link it to your function or frontend, using the link prop.

   Next.js

   new sst.aws.Nextjs("MyWeb", {
     link: [bucket]
   });

   Remix

   new sst.aws.Remix("MyWeb", {
     link: [bucket]
   });

   Astro

   new sst.aws.Astro("MyWeb", {
     link: [bucket]
   });

   Function

   new sst.aws.Function("MyFunction", {
     handler: "src/lambda.handler",
     link: [bucket]
   });

3. Use the SDK to access the linked resource in a typesafe way.

   Next.js

   app/page.tsx

   import { Resource } from "sst";
   
   console.log(Resource.MyBucket.name);

   Remix

   app/routes/_index.tsx

   import { Resource } from "sst";
   
   console.log(Resource.MyBucket.name);

   Astro

   src/pages/index.astro

   ---
   import { Resource } from "sst";
   
   console.log(Resource.MyBucket.name);
   ---

   Function

   src/lambda.ts

   import { Resource } from "sst";
   
   console.log(Resource.MyBucket.name);

---

Working locally

The above applies to your app deployed through sst deploy. To access linked resources locally you’ll need to be running sst dev.

For the frontends, you’ll need to wrap your frontend in the sst dev command.

Next.js

sst dev next dev

Remix

sst dev remix dev

Astro

sst dev astro dev

Function

sst dev

---

How it works

At high level when you link a resource to a function or frontend, the following happens:

1. The function is given permission to access the linked resource.

2. The links that the resource exposes are injected into the function package.

   Tip

   The links a component exposes are listed in its API reference. For example, you can view a Bucket’s links here.

3. The types to access these links are generated.

---

Injecting links

Resource links are injected into your function or frontend package when you run sst dev or sst deploy. But this is done in a slightly different way for both these cases.

Functions

The functions in SST are tree shaken and bundled using esbuild. While bundling, SST injects the resource links into the globalThis.

Frontends

The frontends are not bundled by SST. Instead, when they are built, SST injects the resource links into the process.env object using the prefix SST_RESOURCE_.

This is why when you are running your frontend locally, it needs to be wrapped in the sst dev command.

---

Generating types

When you run sst dev or sst deploy, it generates the types to access the linked resources. These are generated as:

1. A sst-env.d.ts file in the same directory of the nearest package.json of the function or frontend that’s receiving the links. This contains the types for the resources that are linked to it.
2. A .sst/types.generated.ts file that can be referenced from a sst-env.d.ts. This is useful for monorepo packages that don’t have a function or frontend. For example, if you have a core package that contains some shared code.

You can check the generated sst-env.d.ts types into source control. This will let your teammates see the types without having to run sst dev when they pull your changes.