Incremental Static Regeneration for Angular
A library that enables Angular Universal applications to generate static pages at runtime and then update them incrementally on demand or on a schedule.
Features
- ⏰ Scheduled cache invalidation
▶️ On-demand cache invalidation🔌 Plugin based cache handlers👌 No build changes required!🅰️ Supports Angular Universal🛡️ NgModules & Standalone Compatible
How to use it?
- Install npm package
npm install ngx-isr
# or
yarn add ngx-isr
# or
pnpm add ngx-isr
- Initialize
ISRHandler
insideserver.ts
const isr = new ISRHandler({
indexHtml,
invalidateSecretToken: 'MY_TOKEN', // replace with env secret key ex. process.env.REVALIDATE_SECRET_TOKEN
enableLogging: !environment.production
});
- Add invalidation url handler
server.use(express.json());
server.post("/api/invalidate", async (req, res) => await isr.invalidate(req, res));
- Replace Angular default server side rendering with ISR rendering
Replace
server.get('*',
(req, res) => {
res.render(indexHtml, { req, providers: [{ provide: APP_BASE_HREF, useValue: req.baseUrl }] });
}
);
with
server.get('*',
// Serve page if it exists in cache
async (req, res, next) => await isr.serveFromCache(req, res, next),
// Server side render the page and add to cache if needed
async (req, res, next) => await isr.render(req, res, next),
);
You can also pass providers
to each of the ISRHandler
methods.
server.get('*',
...
async (req, res, next) => await isr.render(req, res, next, {
providers: [
{ provide: APP_BASE_HREF, useValue: req.baseUrl }, // <-- Needs to be provided when passing providers
{ provide: CUSTOM_TOKEN, useValue: 'Hello from ISR' },
CustomService
]
}),
);
It is also possible to pass a modifyCachedHtml
or modifyGeneratedHtml
callbacks to the ISRHandler
methods.
These methods provide a way to modify the html served from cache or the html that is generated on the fly.
Important: Use these methods with caution as the logic written can increase the processing time.
server.get('*',
// Serve page if it exists in cache
async (req, res, next) => await isr.serveFromCache(req, res, next, {
modifyCachedHtml: (req, cachedHtml) => {
return `${cachedHtml}<!-- Hello, I'm a modification to the original cache! -->`;
}
}),
// Server side render the page and add to cache if needed
async (req, res, next) => await isr.render(req, res, next, {
modifyGeneratedHtml: (req, html) => {
return `${html}<!-- Hello, I'm modifying the generatedHtml before caching it! -->`
}
}),
);
ISRHandler provides APP_BASE_HREF
by default. And if you want pass providers
into the methods of ISRHandler, you will also have to provide APP_BASE_HREF
token.
- Add
revalidate
key in route data
Example:
{
path: "example",
component: ExampleComponent,
data: { revalidate: 5 },
}
NOTE: Routes that don't have revalidate key in data won't be handled by ISR. They will fallback to Angular default server side rendering pipeline.
- Register providers
To register the ngx-isr providers, you can either import
NgxIsrModule
in yourAppServerModule
or provideprovideISR
in yourAppServerModule
providers.
Or, if you are in a standalone app, you can register the providers in your app.config.server.ts
file.
- Register using
NgxIsrModule
import { NgxIsrModule } from 'ngx-isr/server'; // <-- Import module from library
@NgModule({
imports: [
...
NgxIsrModule.forRoot() // <-- Use it in module imports
]
})
export class AppServerModule {}
- Register using the
provideISR
function
import { provideISR } from 'ngx-isr/server';
@NgModule({
providers: [
provideISR() // <-- Use it in module providers
]
})
export class AppServerModule {}
- Register using the
provideISR
function in standalone app
import { provideISR } from 'ngx-isr/server';
const serverConfig: ApplicationConfig = {
providers: [
provideServerRendering(),
provideISR() // <-- Use it in config providers
],
};
When registering the providers, NgxIsrService
will be initialized and will start to listen to route changes, only on the server side, so the browser bundle won't contain any extra code.
Changelog
Version 0.5.5
Features
- feat: allow
NgxIsrService
to be used in application code without bringing the whole library in the browser bundle - feat: separate the library into secondary entry points for server and browser
BREAKING CHANGES:
Imports now should be done from ngx-isr/server
and ngx-isr/browser
instead of ngx-isr
;
// Before
import { NgxIsrModule } from 'ngx-isr';
// After
import { NgxIsrModule } from 'ngx-isr/server';
// Before
import { provideISR } from 'ngx-isr';
// After
import { provideISR } from 'ngx-isr/server';
Things exported from ngx-isr/server
:
NgxIsrModule
provideISR
ISRHandler
-
FileSystemCacheHandler
andFileSystemCacheOptions
Things exported from ngx-isr/browser
:
NgxIsrService
Things exported from ngx-isr/models
:
CacheHandler
-
CacheISRConfig
(renamed fromISROptions
) CacheData
-
INgxIsrService
andNgxIsrState
ISRHandlerConfig
InvalidateConfig
RenderConfig
ServeFromCacheConfig
RouteISRConfig
Version 0.5.4
Features
- feat: refactor FileSystem cache handler from scratch (fixes: #35)
- fix: buildId can be null but also undefined, added a check for it
Version 0.5.3
Features
-
feat: Introduce
RouteISRConfig
interface for better type safety in route dataHow to use it?
const routes: Rotues = [{ path: 'home', component: HomeComponent, data: { revalidate: 0 } as RouteISRConfig // 👈 Add type to route data }];
-
feat: Added build id support
What is it and why do we need it?
The build id is a unique identifier that is generated for each build. It is used to invalidate the cache when a new build is deployed. So, when a new build is deployed, every page that will be requested will be server-rendered again and not served from the cache. This way, the users will always get the latest version of the application.
Useful when you have an external cache handler like Redis.
How to use it?
To use it, you need to pass the build id to the
ISRHandler
constructor. Angular itself doesn't generate a build id. But we can generate it using the environment file. What we can do is to set field in the environment file calledbuildId
and set it to:new Date().getTime(),
.Ex. environment.ts:
export const environment = { production: false, buildId: new Date().getTime() + '', // We need to convert it to string because the buildId is a string };
This way we will have a unique build id for each build because the buildId will evaluated at build time. Then, we pass the build id to the ISRHandler constructor.
Ex. server.ts:
import { environment } from './src/environments/environment'; const isr = new ISRHandler({ .. other options buildId: environment.buildTimestamp // Pass the build id });
-
fix: Fixed a bug where the cache was not invalidated when the build id changed
Breaking changes:
-
ISROptions
is being deprecated. UseCacheISRConfig
instead.
Version 0.5.2
- feat: Migrate repository to nx workspace
- feat: Added
provideISR
provider function - chore: Update example RedisCacheHandler to use a prefix
License
MIT