Skip to content

Commit 23e910f

Browse files
conico974vicb
andauthored
Docs(aws): custom overrides for aws (#35)
Co-authored-by: Victor Berchet <[email protected]>
1 parent c0d3199 commit 23e910f

13 files changed

+98
-10
lines changed

pages/aws/config/_meta.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@
33
"custom_overrides": "Custom Overrides",
44
"reference": "Reference",
55
"full_example": "Full Example",
6-
"nx": "Nx Monorepo"
6+
"nx": "Nx Monorepo",
7+
"overrides": "Overrides"
78
}
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"wrapper": "Wrapper",
3+
"converter": "Converter",
4+
"incremental_cache": "Incremental Cache",
5+
"tag_cache": "Tag Cache",
6+
"queue": "Revalidation Queue",
7+
"image_loader": "Image Loader",
8+
"proxy_external_request": "External Request Proxy",
9+
"origin_resolver": "Origin Resolver",
10+
"invoke_function": "Invoke Function for the warmer"
11+
}
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
This override is meant to convert request and response provided from your wrapper to the internal types that are used by OpenNext.
2+
3+
If you want to better understand how to implement your own Converter, the easiest way would be to take a look at one of the existing [included Converter](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/converters)
4+
5+
Couple of things to note :
6+
- If you use a `StreamCreator` in your wrapper, you probably don't need to do anything in the `convertTo` function.
7+
- If used for the default, the image optimization, or one of the splitted server the internal types will be `InternalEvent` and `InternalResult` respectively.
8+
- If used for the external middleware, the internal types will be `InternalEvent` and `InternalResult | MiddlewareOutputEvent` respectively.
9+
- For the other servers, look up their respective types in the codebase.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
This override is used by OpenNext and more specifically by the image server to be able to load images from a custom source. Images are not bundled with the image server and are loaded from the source specified in the override.
2+
3+
This is used for internal image only (i.e. src without host). External source are already handled by the image server.
4+
5+
If you want to better understand how to implement your own ImageLoader, the easiest way would be to take a look at the existing [included ImageLoader](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/imageLoader).
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
This override is used by the [`cache` adapter](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/adapters/cache.ts) that is provided by OpenNext to the NextServer. It is also used by OpenNext if `enableCacheInterception` is set to `true` in the configuration.
2+
3+
It is used for retrieving and updating the ISR/SSG cache as well as the fetch cache used by Next.js. It does not handle anything related to cache tags (i.e. `revalidateTag` and `revalidatePath`)
4+
5+
If you want to better understand how to implement your own IncrementalCache, the easiest way would be to take a look at the existing [included IncrementalCache](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/incrementalCache).
6+
7+
One thing to note is that it is not used at build time, only at runtime. This means that you'll have to upload the cache yourself if you want to use the prebuilt routes/pages (And this is mandatory for ISR/SSG routes with `fallback:false`).
8+
All the cache files are present in the `.open-next/cache` folder. The one under `BUILD_ID` are for the ISR/SSG cache and the one under `__fetch/BUILD_ID` are for the fetch cache.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
This override is used by OpenNext to invoke the function for warmup purposes. It is only used in the warmer server.
2+
3+
If you want to better understand how to implement your own InvokeFunction, the easiest way would be to take a look at the existing [included InvokeFunction](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/warmer).
4+
5+
You could override this to provide some custom logic to invoke more or less function depending on the hour for example.
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
This override is used by OpenNext to resolve the origin of the request. This is for internal requests only and is needed to support the `external` middleware.
2+
This is only used by the external middleware.
3+
4+
At build time, we may not know where the splitted server will be deployed, so we need to resolve the origin at runtime. This is why we need this override. The origin is resolved by this override will need to be handled by the wrapper used. At the moment, only the `aws-cloudfront` and the `cloudflare-edge` wrapper are able to do so.
5+
6+
If you want to better understand how to implement your own OriginResolver, the easiest way would be to take a look at the existing [included OriginResolver](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/originResolver).
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
This override is used by OpenNext to proxy rewritten requests to external services. It is used either in the `external` middleware (if set) or in the default/splitted server if the middleware is bundled.
2+
3+
If you want to better understand how to implement your own ProxyExternalRequest, the easiest way would be to take a look at the existing [included ProxyExternalRequest](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/proxyExternalRequest).
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
This override is used by OpenNext to trigger the revalidation of stale routes.
2+
Before sending the response to the client, OpenNext will check if the route is stale and if it is, it will call the queue override to revalidate the route.
3+
4+
If you want to better understand how to implement your own Queue, the easiest way would be to take a look at the existing [included Queue](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/queue).
5+
6+
Couple of things to note :
7+
- The default implementation use an SQS queue. This has the main advantage of being able to control the concurrency of the revalidations as well as avoiding trigerring the revalidation multiple times for the same route.
8+
- You don't have to use a queue at all. You could trigger the revalidation directly in the Queue override itself. You can see a very simple implementation of this [in the `queue` override](/aws/contribute/local_run#devqueuets).
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
This override is used by the [`cache` adapter](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/adapters/cache.ts) that is provided by OpenNext to the NextServer. It is also used by OpenNext if `enableCacheInterception` is set to `true` in the configuration and by the `initializationFunction` for prepopulating the cache.
2+
3+
It is used for the cache tags (i.e. `revalidateTag` and `revalidatePath`). It does not handle anything related to the ISR/SSG cache or the fetch cache used by Next.js.
4+
It's main role is to detremine if a path is stale based on the tags and also to update the tag cache when `revalidateTag` is called.
5+
6+
The current implementation differs from the way Next.js standalone handle cache tags. In the standalone version, the cache tags are stored in a file, and every time a cache entry is accessed, it has to check for every tags if the entry is stale. This approach is very read heavy and doesn't work well with DB like DynamoDB.
7+
We choose to go another way. We store tags for every path that exists in the cache. This way, we can easily know if a path is stale by just checking the path instead of every tags used. This approach is more write heavy but it's a tradeoff we are willing to make.
8+
This also has the drawback of needing to prepopulate the cache with all the tags that are used in the application. This is done by the `initializationFunction`.
9+
10+
We might allow to choose how cache tags are handled in the future depending on the `TagCache` implementation. If you need this feature, feel free to open an issue on the [GitHub repository](https://github.com/opennextjs/opennextjs-aws).
11+
12+
If you want to better understand how to implement your own TagCache, the easiest way would be to take a look at the existing [included TagCache](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/tagCache).

0 commit comments

Comments
 (0)