polotno-node 2.12.29 → 2.13.0

package/README.md

@@ -67,6 +67,10 @@ const instance = await createInstance({
   // useful to set your own rendering props or use browserless
   browser: browser,
 
+  // browserArgs - additional browser arguments to append to default args
+  // see "Custom Browser Arguments" section for more details
+  browserArgs: ['--custom-arg'],
+
   // requestInterceptor - optional function to intercept and modify network requests
   // Useful when you need to:
   // - Modify headers like User-Agent to access protected image resources
@@ -89,6 +93,28 @@ const instance = await createInstance({
 });
 ```
 
+### `createBrowser(options)`
+
+Create a Puppeteer browser instance with optimized settings for Polotno rendering. This is useful when you want to create a browser separately from the instance.
+
+```js
+const { createBrowser, createInstance } = require('polotno-node');
+
+// Create a browser
+const browser = await createBrowser({
+  browserArgs: ['--custom-arg'], // optional: additional browser arguments
+  // ... any other puppeteer.launch options
+});
+
+// Create instance with the browser
+const instance = await createInstance({
+  key: 'your-key',
+  browser: browser,
+});
+```
+
+**Note:** `createBrowser()` automatically uses the optimized `args` for rendering. You can add custom arguments via the `browserArgs` parameter.
+
 ### `instance.jsonToDataURL(json, attrs)`
 
 Export json into data URL.
@@ -204,14 +230,30 @@ Timeout for loading fonts. By default it is 6000ms.
 const url = await instance.jsonToPDFDataURL(json, { fontLoadTimeout: 10000 });
 ```
 
-### `attrs.htmlTextRenderEnabled`
+### `attrs.richTextEnabled`
+
+Enable rich text renderin. By default it is `false`.
+
+```js
+const url = await instance.jsonToPDFDataURL(json, {
+  richTextEnabled: true,
+});
+```
+
+### `attrs.htmlTextRenderEnabled` (deprecated)
 
-Enabled experimental HTML text rendering. By default it is `false`.
+⚠️ **Deprecated:** Use `richTextEnabled` instead. This property is maintained for backward compatibility and works as a fallback.
 
 ```js
+// Old (deprecated)
 const url = await instance.jsonToPDFDataURL(json, {
   htmlTextRenderEnabled: true,
 });
+
+// New (recommended)
+const url = await instance.jsonToPDFDataURL(json, {
+  richTextEnabled: true,
+});
 ```
 
 ### `attrs.textVerticalResizeEnabled`
@@ -300,332 +342,245 @@ You should be able to change config before you call `store.loadJSON` function an
 ```js
 const url = await instance.run(async (json) => {
   // you can use global "config" object that has some functions from "polotno/config" module
-  window.config.unstable_setTextVerticalResizeEnabled(true);
+  window.config.setTextVerticalResizeEnabled(true);
   // you can use global "store" object
   store.loadJSON(json);
   return store.toDataURL();
 }, json);
 ```
 
-## Your own client
+## Custom Browser Arguments
 
-By default `polotno-node` ships with the default Polotno Editor with its (hopefully) last version. If you use experimental API such as `unstable_registerShapeModel` and `unstable_registerShapeComponent`, the rendering may fail if you use unknown elements types.
+### Using `args` export
 
-In that case you can use your own client editor. You need to create a public html page with `store` as global variable and mount just `<Workspace />` component from `polotno/canvas` module. Take a look into `client.html` file and `client.js` file in this repo as a demo. In your own version of the Editor you can use experimental API to define custom components.
+`polotno-node` exports a carefully curated set of Chrome arguments (`args`) that are optimized for server-side rendering. These arguments are automatically used when you call `createInstance()` without providing your own browser.
 
-Pass `url` option to `createInstance` function with public url of your client editor.
+```js
+const { args } = require('polotno-node');
 
-**Note: you will have to maintain the last version of your client editor by yourself. Better to keep using the last **
+console.log(args);
+// Will show the default arguments like:
+// ['--disable-web-security', '--allow-file-access-from-files', '--disable-gpu', ...]
+```
+
+**Platform compatibility:** Using `@sparticuz/chromium` args works best on **Linux** and **macOS**. On **Windows**, these args may not work as expected, so the library automatically skips them on Windows. When manually combining args, be aware of platform differences.
+
+### Using with custom browser
+
+When you want to use your own browser instance (e.g., with browserless.io or custom puppeteer configuration), you should combine `chrome.args` (the base defaults) with polotno-node's `args` (additional optimizations):
 
 ```js
-const { createInstance } = require('polotno-node');
+const { createInstance, args } = require('polotno-node');
+const chromium = require('@sparticuz/chromium');
+const puppeteer = require('puppeteer-core');
+
+// Combine chrome.args (base defaults) with polotno-node's args (optimizations)
+// This works best on Linux/macOS
+const browser = await puppeteer.launch({
+  args: [...chromium.args, ...args],
+  defaultViewport: chromium.defaultViewport,
+  executablePath: await chromium.executablePath(),
+  headless: true,
+  ignoreHTTPSErrors: true,
+});
 
 const instance = await createInstance({
-  key: 'KEY',
-  url: 'https://yourappdomain.com/client',
+  key: 'your-key',
+  browser,
 });
 ```
 
-## Usage on the cloud
+**Note:** `polotno-node`'s `args` are designed to work on top of `@sparticuz/chromium`'s args for optimal server-side rendering on Linux/macOS environments.
 
-### AWS EC2
+### Modifying default arguments
 
-EC2 has some troubles with loading fonts. To fix the issue install Google Chrome, it will load all required libraries.
+If you need to add, remove, or replace specific arguments (Linux/macOS):
 
-```bash
-curl https://intoli.com/install-google-chrome.sh | bash
-```
+```js
+const { createInstance, args } = require('polotno-node');
+const chromium = require('@sparticuz/chromium');
+const puppeteer = require('puppeteer-core');
 
-Got it from here: https://github.com/puppeteer/puppeteer/issues/765#issuecomment-353694116
+// Add custom arguments on top of chrome.args and polotno args
+const browser = await puppeteer.launch({
+  args: [...chromium.args, ...args, '--custom-arg', '--another-custom-arg'],
+  defaultViewport: chromium.defaultViewport,
+  executablePath: await chromium.executablePath(),
+});
 
-### Browserless usage
+// Remove specific arguments from polotno args
+const filteredArgs = args.filter((arg) => arg !== '--disable-gpu');
+const browser2 = await puppeteer.launch({
+  args: [...chromium.args, ...filteredArgs],
+  defaultViewport: chromium.defaultViewport,
+  executablePath: await chromium.executablePath(),
+});
 
-You can speed up your function execution a lot, if instead of using full browser you will use [browserless.io](https://browserless.io/) service. It is a paid service not affiliated with Polotno.
+// Replace specific arguments in polotno args
+const customArgs = args.map((arg) =>
+  arg === '--disable-web-security' ? '--enable-web-security' : arg
+);
+const browser3 = await puppeteer.launch({
+  args: [...chromium.args, ...customArgs],
+  defaultViewport: chromium.defaultViewport,
+  executablePath: await chromium.executablePath(),
+});
+```
 
-Using browserless.io you can also make your function much smaller in size, so it will be possible to deploy to cloud provider with smaller limits, like Vercel.
+**Note:** These examples assume Linux/macOS environment where `chromium.args` work properly.
+
+### Combining with `browserArgs` option
+
+When using `createInstance()` or `createBrowser()`, you can provide additional arguments via `browserArgs` option. Internally, this automatically combines `chrome.args` + `args` + your custom `browserArgs`:
 
 ```js
-// (!) loading from polotno-node/instance will not import puppeteer and chromium-min dependencies
-const { createInstance } = require('polotno-node/instance');
-const puppeteer = require('puppeteer');
+const { createInstance } = require('polotno-node');
 
 const instance = await createInstance({
-  key: 'nFA5H9elEytDyPyvKL7T',
-  browser: await puppeteer.connect({
-    browserWSEndpoint: 'wss://chrome.browserless.io?token=API_KEY',
-  }),
-  url: 'https://yourappdomain.com/client', // see "Your own client" section
+  key: 'your-key',
+  browserArgs: ['--custom-arg', '--another-arg'],
 });
+// Internally merges: chrome.args + polotno args + browserArgs
 ```
 
-### Minimal usage
+## Your own client
 
-Also you can use [@sparticuz/chromium-min](https://github.com/Sparticuz/chromium#-min-package) to reduce function size. Make sure it is caching chromium binary in your cloud provider. Looks like Vercel is NOT doing that!
+By default `polotno-node` ships with the default Polotno Editor with its (hopefully) last version. If you use experimental API such as `unstable_registerShapeModel` and `unstable_registerShapeComponent`, the rendering may fail if you use unknown elements types.
 
-```bash
-npm install @sparticuz/chromium-min
-```
+In that case you can use your own client editor. You need to create a public html page with `store` as global variable and mount just `<Workspace />` component from `polotno/canvas` module. Take a look into `client.html` file and `client.js` file in this repo as a demo. In your own version of the Editor you can use experimental API to define custom components.
 
-```js
-const { createInstance } = require('polotno-node/instance');
-const chromium = require('@sparticuz/chromium-min');
-const puppeteer = require('puppeteer-core');
+Pass `url` option to `createInstance` function with public url of your client editor.
 
-const makeInstance = async () => {
-  const browser = await puppeteer.launch({
-    args: [
-      ...chromium.args,
-      '--no-sandbox',
-      '--hide-scrollbars',
-      '--disable-web-security',
-      '--allow-file-access-from-files',
-      // more info about --disable-dev-shm-usage
-      // https://github.com/puppeteer/puppeteer/issues/1175#issuecomment-369728215
-      // https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md#tips
-      '--disable-dev-shm-usage',
-    ],
-    defaultViewport: chromium.defaultViewport,
-    executablePath: await chromium.executablePath(
-      'https://github.com/Sparticuz/chromium/releases/download/v110.0.1/chromium-v110.0.1-pack.tar'
-    ),
-    headless: chromium.headless,
-    ignoreHTTPSErrors: true,
-  });
+**Note: you will have to maintain the last version of your client editor by yourself. Better to keep using the last **
 
-  return await createInstance({
-    key: 'your-key',
-    browser,
-  });
-};
+```js
+const { createInstance } = require('polotno-node');
 
-const instance = await makeInstance();
+const instance = await createInstance({
+  key: 'KEY',
+  url: 'https://yourappdomain.com/client',
+});
 ```
 
-## AWS lambda with Layer configuration
-
-In order to run the **polotno-node** in AWS Lambda, it's recommended to use a [Lambda Layer configurations](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html) which will manage the dependencies, like **chronium**.
-In addition, the Lambda's configuration needs to be changed as well. It's recommeded to change the **timeout** to 30 seconds instead of default value (3 seconds) and **Memory limit** increase to minimum 512 Mb instead of 128 mb ( default value ).
-
-Dependencies:
-
-- @sparticuz/chromium
-- puppeteer-core
-- polotno-node
-
-Pre-requirements:
+## Usage on the cloud
 
-- The chronium and puppeteer versions need to be satisfied. Please check this [document](https://pptr.dev/supported-browsers).
-- The **minumum Memory limit** needs to be `512 Mb` for AWS Lambda. Default is `128 Mb`.
-- The **timeout** should be increased from default 3 seconds to higher value, for example up to 30 seconds. It depends on the Memory limit. For instance, if the memory limit was set to 1024, the polotno process might take ~15 secs, if 512 mb, ~30sec.
+### AWS Lambda
 
-==========================================
+`polotno-node` works with AWS Lambda out of the box. Here's a simple example:
 
-How to create a configuration layer with a dependency on `chronium` ?
+```js
+const { createInstance } = require('polotno-node');
 
-1. Create a `.zip` file from a chronium project. For example:
+export const handler = async (event) => {
+  const instance = await createInstance({
+    key: process.env.POLOTNO_API_KEY,
+  });
 
-```shell
-mkdir chronium-112 && cd chronium-112
+  const base64 = await instance.jsonToImageBase64(event.json);
 
-npm init -y
-npm install @sparticuz/chromium@112.0
+  await instance.close();
 
-zip -r chronium.zip ./*
+  return {
+    statusCode: 200,
+    headers: {
+      'Content-Type': 'image/png',
+    },
+    body: base64,
+  };
+};
 ```
 
-2. Go to AWS console then open a Lambda section and click on `Layers`.
-3. Following the [documentation](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html) create a Layer with a chrnioum dependency by uploading a zip file. Keep in mind that environment like `nodejs18.x` should match between layer and function.
+**Important:** For reliable performance, you may need to increase AWS Lambda limits:
 
-> Approximatelly, the size of the zip, will be around `73 Mb`, so in order to upload, the S3 service will be needed. 4. Finally, open the Lambda function, select a `Code` section, at the bottom click on `Add Layer` and select a created layer.
+- **Memory**: Increase from the default. For complex designs, you may need to set it to maximum.
+- **Timeout**: Increase from the default. For large files, you may need to set it to maximum.
+- **Ephemeral Storage**: May need to increase from the default for complex designs.
 
-==========================================
+Without these increases, polotno-node may work on smaller files but will fail or timeout on larger files.
 
-How to run the full example with aws-cli ?
+**Full working example:** See [polotno-node-aws-lambda](https://github.com/polotno-project/polotno-node-aws-lambda) for a complete demo.
 
-### 1. Create a Lambda configuration layer
+#### AWS Lambda with Layers (Optional)
 
-Create a Lambda configuration layer, and upload a **.zip** archive which stores a **chronium** npm or git package.
+For advanced usage, you can use [Lambda Layers](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html) to manage dependencies like chromium separately. This can help with deployment size and organization.
 
-```shell
-export CH_VERSION=112.0
-export BUCKET=example-bucket
-export AWS_ACC_ID=000000000000
+**Dependencies:**
 
-# create a chronium project for Layer
-mkdir chronium-layer
-cd chronium-layer
-npm init -y
-npm install @sparticuz/chromium@${CH_VERSION}
-zip -r chronium.zip ./*
+- @sparticuz/chromium
+- puppeteer-core
+- polotno-node
 
-# upload a Layer to S3
-aws s3 cp chronium.zip s3://${BUCKET}/lambda-layers/chronium-${CH_VERSION}.zip
+**Requirements:**
 
-# publish a Layer so it can be used in Lambda
-aws lambda publish-layer-version \
---layer-name chronium-polotno \
---content "S3Bucket=${BUCKET},S3Key=lambda-layers/chronium-{CH_VERSION}.zip" \
---description Chronium-dev-${CH_VERSION} \
---compatible-architectures x86_64 \
---compatible-runtimes nodejs18.x
-```
+- The chromium and puppeteer versions need to be compatible. Please check this [document](https://pptr.dev/supported-browsers).
+- The **Memory limit** needs to be increased from the default. You may need to set it to maximum for complex designs.
+- The **timeout** should be increased from the default. You may need to set it to maximum for large files.
 
-### 2. Create a JS file for a Lambda's handler
+**Creating a Lambda Layer with chromium:**
 
-#### Init a node project
+1. Create a `.zip` file from a chromium project:
 
 ```shell
-# create a folder
-mkdir handler && cd handler
+mkdir chromium-112 && cd chromium-112
 
-# init a node project
 npm init -y
+npm install @sparticuz/chromium@112.0
 
-# install dependencies
-npm install --save polotno-node puppeteer-core@19.8.0
+zip -r chromium.zip ./*
 ```
 
-#### Create a handler
+2. Go to AWS console then open Lambda section and click on `Layers`.
+3. Following the [documentation](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html) create a Layer with a chromium dependency by uploading a zip file. Keep in mind that environment like `nodejs18.x` should match between layer and function.
 
-```shell
-# create a file handler
-touch index.mjs
-
-# add code example
-echo "
-import chromium from "@sparticuz/chromium";
-import puppeteer from "puppeteer-core";
-import { createInstance } from "polotno-node";
-export const handler = () => {
-  const browser = await puppeteer.launch({
-    args: [
-      ...chromium.args,
-      "--no-sandbox",
-      "--hide-scrollbars",
-      "--disable-web-security",
-      "--allow-file-access-from-files",
-      "--disable-dev-shm-usage",
-    ],
-    defaultViewport: chromium.defaultViewport,
-    executablePath: await chromium.executablePath(),
-    headless: true,
-    ignoreHTTPSErrors: true,
-  });
-  const polotnoInstance = await createInstance({
-    key: process.env.POLOTNO_API_KEY,
-    browser,
-  });
-  const body = polotnoInstance.jsonToImageBase64(event.json)
+> The size of the zip will be large, so you may need to use S3 to upload it.
 
-  return {
-    StatusCode: 200,
-    headers: {
-      'Content-Type': 'image/png'
-    },
-    body,
-  }
-};
-" >> index.mjs
-```
+4. Finally, open the Lambda function, select a `Code` section, at the bottom click on `Add Layer` and select a created layer.
 
-<details>
-<summary>Highlighted code example from the command above:</summary>
+**Handler code with custom chromium:**
+
+Create `index.mjs`:
 
 ```js
-import chromium from "@sparticuz/chromium";
-import puppeteer from "puppeteer-core";
-import { createInstance } from "polotno-node";
-export const handler = () => {
+import chromium from '@sparticuz/chromium';
+import puppeteer from 'puppeteer-core';
+import { createInstance, args } from 'polotno-node';
+
+export const handler = async (event) => {
   const browser = await puppeteer.launch({
-    args: [
-      ...chromium.args,
-      "--no-sandbox",
-      "--hide-scrollbars",
-      "--disable-web-security",
-      "--allow-file-access-from-files",
-      "--disable-dev-shm-usage",
-    ],
+    // Combine chromium args with polotno-node's optimized args
+    // Works well on AWS Lambda (Linux environment)
+    args: [...chromium.args, ...args],
     defaultViewport: chromium.defaultViewport,
     executablePath: await chromium.executablePath(),
     headless: true,
     ignoreHTTPSErrors: true,
   });
+
   const polotnoInstance = await createInstance({
     key: process.env.POLOTNO_API_KEY,
     browser,
   });
-  const body = polotnoInstance.jsonToImageBase64(event.json)
+
+  const body = await polotnoInstance.jsonToImageBase64(event.json);
+
+  await polotnoInstance.close();
 
   return {
-    StatusCode: 200,
+    statusCode: 200,
     headers: {
-      'Content-Type': 'image/png'
+      'Content-Type': 'image/png',
     },
     body,
-  }
+  };
 };
 ```
 
-</details>
-
-#### Create file with variables
-
-```shell
-echo '{
-    "Variables": {
-      "POLOTNO_API_KEY": "your-api-key"
-    }
-  }
-' >> vars.json
-
-# archive the folder
-zip -r index.zip ./*
-
-# copy to S3
-aws s3 cp index.zip s3://${BUCKET}/polotno-handler.zip
-```
-
-#### Crete a trust policy
-
-```shell
-echo '{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Principal": {
-        "Service": "lambda.amazonaws.com"
-      },
-      "Action": "sts:AssumeRole"
-    }
-  ]
-}
-' >> trustPolicy.json
-```
-
-#### Create roles and policies in AWS
-
-```shell
-aws iam create-role --role-name lambda-polotno-role --assume-role-policy-document file://trustPolicy.json
-aws iam attach-role-policy --role-name lambda-polotno-role --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
-aws lambda create-function --function-name lambda-polotno \
---runtime nodejs18.x \
---zip-file fileb://index.zip \
---layers "arn:aws:lambda:eu-central-1:${AWS_ACC_ID}:layer:chronium-polotno:1" \
---handler index.handler \
---environment file://vars.json \
---role "arn:aws:iam::${AWS_ACC_ID}:role/lambda-polotno-role" \
---timeout 60 \
---memory-size 512
-// try it
-aws lambda invoke --function-name lambda-polotno --cli-binary-format raw-in-base64-out --payload file://polotno-project-json.json image
-```
+#### AWS Lambda fonts issue
 
-### AWS Lambda fonts issue
+Lambda functions do not include any fonts by default. If you encounter `Timeout for loading font <font name>` errors, you need to provide basic fonts (Arial and Times or their analogs).
 
-If you have faced an issue `Timeout for loading font <font name>`, please proceed to the next solution.
-
-Lambda functions does not include any fonts by default, so we need to provide basic fonts (Arial and Times or their analogs) to make sure Polotno fonts functionality is working correctly.
+<details>
+<summary>Solution: Add fonts to your Lambda function</summary>
 
 1. Create a `fonts` folder in the root of your handler project.
 
@@ -662,6 +617,75 @@ mkdir fonts
 
 4. Upload your Lambda function as usual, fonts will be loaded automatically.
 
+</details>
+
+### AWS EC2
+
+EC2 has some troubles with loading fonts. To fix the issue install Google Chrome, it will load all required libraries.
+
+```bash
+curl https://intoli.com/install-google-chrome.sh | bash
+```
+
+Got it from here: https://github.com/puppeteer/puppeteer/issues/765#issuecomment-353694116
+
+### Browserless usage
+
+You can speed up your function execution a lot, if instead of using full browser you will use [browserless.io](https://browserless.io/) service. It is a paid service not affiliated with Polotno.
+
+Using browserless.io you can also make your function much smaller in size, so it will be possible to deploy to cloud provider with smaller limits, like Vercel.
+
+```js
+// (!) loading from polotno-node/instance will not import puppeteer and chromium-min dependencies
+const { createInstance } = require('polotno-node/instance');
+const puppeteer = require('puppeteer');
+
+const instance = await createInstance({
+  key: 'nFA5H9elEytDyPyvKL7T',
+  browser: await puppeteer.connect({
+    browserWSEndpoint: 'wss://chrome.browserless.io?token=API_KEY',
+  }),
+  url: 'https://yourappdomain.com/client', // see "Your own client" section
+});
+```
+
+### Minimal usage
+
+Also you can use [@sparticuz/chromium-min](https://github.com/Sparticuz/chromium#-min-package) to reduce function size. Make sure it is caching chromium binary in your cloud provider. Looks like Vercel is NOT doing that!
+
+```bash
+npm install @sparticuz/chromium-min
+```
+
+```js
+const { createInstance } = require('polotno-node/instance');
+// Import args from main entry point for optimal browser configuration
+const { args } = require('polotno-node');
+const chromium = require('@sparticuz/chromium-min');
+const puppeteer = require('puppeteer-core');
+
+const makeInstance = async () => {
+  const browser = await puppeteer.launch({
+    // Combine chromium args with polotno-node's optimized args
+    // Best for Linux/macOS environments
+    args: [...chromium.args, ...args],
+    defaultViewport: chromium.defaultViewport,
+    executablePath: await chromium.executablePath(
+      'https://github.com/Sparticuz/chromium/releases/download/v110.0.1/chromium-v110.0.1-pack.tar'
+    ),
+    headless: chromium.headless,
+    ignoreHTTPSErrors: true,
+  });
+
+  return await createInstance({
+    key: 'your-key',
+    browser,
+  });
+};
+
+const instance = await makeInstance();
+```
+
 ## Troubleshooting
 
 If you have an error like this