176 lines
6.9 KiB
Markdown
176 lines
6.9 KiB
Markdown
# Corerender
|
||
A rendering service for serve.zone that preserves styles for web components.
|
||
|
||
## Install
|
||
|
||
To install Corerender in your project, you can use npm. Make sure you have Node.js installed and then run the following command in your terminal:
|
||
|
||
```shell
|
||
npm install corerender
|
||
```
|
||
|
||
This will add `corerender` as a dependency to your project, allowing you to use its rendering services to preserve styles for web components efficiently.
|
||
|
||
## Usage
|
||
|
||
Welcome to the comprehensive usage guide for `corerender`, a powerful rendering service designed to integrate seamlessly within your web applications, ensuring that styles for web components are preserved properly. The guide is structured to provide a thorough understanding of `corerender`'s capabilities, demonstrating its flexibility and efficiency through realistic scenarios.
|
||
|
||
### Setting Up Your Environment
|
||
|
||
First things first, let’s get `corerender` up and running in your project. Ensure you've installed the package as detailed in the [Install](#install) section. Since `corerender` is a TypeScript-friendly library, it is recommended to use TypeScript for development to leverage the full power of type safety and IntelliSense.
|
||
|
||
### Basic Render Service Setup
|
||
|
||
```typescript
|
||
import { Rendertron } from 'corerender';
|
||
|
||
const rendertronInstance = new Rendertron();
|
||
|
||
(async () => {
|
||
console.log('Starting rendertron...');
|
||
await rendertronInstance.start();
|
||
console.log('Rendertron started successfully!');
|
||
})();
|
||
|
||
```
|
||
|
||
The code initializes an instance of `Rendertron` and starts the service asynchronously. `Rendertron` is the core class responsible for managing the rendering processes, including task scheduling and storing rendering results persistently in a database.
|
||
|
||
### Understanding the Rendertron Architecture
|
||
|
||
The architecture of `Rendertron` is designed to support web component rendering through several integral components:
|
||
|
||
1. **Prerender Manager**: Manages the creation and retrieval of prerender results.
|
||
2. **Task Manager**: Handles scheduling tasks for prerendering operations and cleanup routines.
|
||
3. **Utility Service Server**: Provides the server interface that accepts/render requests and serves prerendered content efficiently.
|
||
|
||
### Using the Prerender Manager
|
||
|
||
The `PrerenderManager` is responsible for generating and caching the rendering results of webpages. Here’s how you can use the `PrerenderManager` to prerender a webpage:
|
||
|
||
```typescript
|
||
import { PrerenderManager } from 'corerender/dist_ts/rendertron.classes.prerendermanager';
|
||
|
||
(async () => {
|
||
const prerenderManager = new PrerenderManager();
|
||
await prerenderManager.start();
|
||
|
||
const urlToPrerender = 'https://example.com';
|
||
const prerenderResult = await prerenderManager.getPrerenderResultForUrl(urlToPrerender);
|
||
console.log(`Prerendered content for ${urlToPrerender}:`);
|
||
console.log(prerenderResult);
|
||
|
||
await prerenderManager.stop();
|
||
})();
|
||
```
|
||
|
||
The above script demonstrates accessing a webpage's prerendered content. It initializes the `PrerenderManager`, specifies a URL, and requests the rendering result, which is stored or retrieved from the database.
|
||
|
||
### Scheduling Prerendering Tasks
|
||
|
||
The `TaskManager` class allows for efficiently scheduling tasks, such as regular prerendering of local domains and cleanup of outdated render results:
|
||
|
||
```typescript
|
||
import { TaskManager } from 'corerender/dist_ts/rendertron.taskmanager';
|
||
|
||
const taskManager = new TaskManager(rendertronInstance);
|
||
taskManager.start();
|
||
|
||
// Example: Manual trigger of a specific task
|
||
taskManager.triggerTaskByName('prerenderLocalDomains');
|
||
|
||
taskManager.stop();
|
||
```
|
||
|
||
`TaskManager` works closely with the `Rendertron` service to ensure tasks are executed as per defined schedules (e.g., every 30 minutes or daily). It allows manual triggering for immediate execution outside the schedule.
|
||
|
||
### Managing Render Results
|
||
|
||
The pre-rendered results are stored using `smartdata`’s `SmartDataDbDoc`. You may need advanced control over whether these are retrieved, created anew, or updated:
|
||
|
||
```typescript
|
||
import { PrerenderResult } from 'corerender/dist_ts/rendertron.classes.prerenderresult';
|
||
|
||
(async () => {
|
||
const url = 'https://example.com';
|
||
let prerenderResult = await PrerenderResult.getPrerenderResultForUrl(prerenderManager, url);
|
||
|
||
// Check if an updated result is necessary
|
||
if (prerenderResultNeedsUpdate(prerenderResult)) {
|
||
prerenderResult = await PrerenderResult.createPrerenderResultForUrl(prerenderManager, url);
|
||
}
|
||
|
||
console.log(`Final Prerendered content for ${url}:`, prerenderResult.renderResultString);
|
||
})();
|
||
```
|
||
|
||
### Integrating with External Systems
|
||
|
||
`Corerender` can be integrated into broader systems that programmatically manage URLs and rendering frequencies. For instance, parsing and prerendering sitemaps:
|
||
|
||
```typescript
|
||
class IntegrationExample {
|
||
private prerenderManager: PrerenderManager;
|
||
|
||
constructor() {
|
||
this.prerenderManager = new PrerenderManager();
|
||
}
|
||
|
||
async prerenderFromSitemap(sitemapUrl: string) {
|
||
await this.prerenderManager.prerenderSitemap(sitemapUrl);
|
||
console.log('Finished prerendering sitemap:', sitemapUrl);
|
||
}
|
||
}
|
||
|
||
(async () => {
|
||
const integrationExample = new IntegrationExample();
|
||
await integrationExample.prerenderFromSitemap('https://example.com/sitemap.xml');
|
||
})();
|
||
```
|
||
|
||
### Server-Side Rendering Directly with SmartSSR
|
||
|
||
`Rendertron` uses the highly efficient `smartssr` for SSR requests. You can easily direct incoming server requests to utilize this rendering pipeline:
|
||
|
||
```typescript
|
||
import { typedserver } from 'corerender/dist_ts/rendertron.plugins';
|
||
|
||
const serviceServerInstance = new typedserver.utilityservers.UtilityServiceServer({
|
||
serviceDomain: 'rendertron.example.com',
|
||
serviceName: 'RendertronService',
|
||
serviceVersion: '2.0.61', // Replace with dynamic version retrieval if needed
|
||
addCustomRoutes: async (serverArg) => {
|
||
serverArg.addRoute(
|
||
'/render/*',
|
||
new typedserver.servertools.Handler('GET', async (req, res) => {
|
||
const requestedUrl = req.url.replace('/render/', '');
|
||
const prerenderedContent = await prerenderManager.getPrerenderResultForUrl(requestedUrl);
|
||
res.write(prerenderedContent);
|
||
res.end();
|
||
})
|
||
);
|
||
},
|
||
});
|
||
|
||
(async () => {
|
||
await serviceServerInstance.start();
|
||
console.log('SSR Server Started');
|
||
})();
|
||
```
|
||
|
||
### Customizing the Logger
|
||
|
||
`Rendertron` employs the `smartlog` package for logging activities across the service. To customize logging, instantiate a logger with custom configurations:
|
||
|
||
```typescript
|
||
import { smartlog } from 'corerender/dist_ts/rendertron.plugins';
|
||
|
||
const customLogger = smartlog.Smartlog.create({ /* custom options */ });
|
||
customLogger.log('info', 'Custom logger integrated successfully.');
|
||
```
|
||
|
||
### Closing Remarks
|
||
|
||
With these examples, you should have a robust understanding of how to implement `corerender` in your web application. It’s a powerful service that takes care of rendering optimizations, allowing developers to focus on building components and architecture, with clear workflows to handle tasks and results efficiently.
|
||
|
||
undefined |