PixlrSDK is a library that allows you to integrate Pixlr's image editing capabilities directly into your web applications. It provides an easy-to-use API to open and edit images in an embedded Pixlr editor within an iframe.
To obtain API Access keys, you must first register an account at Pixlr.com. After creating your account, you can generate your API Access keys by visiting this page and navigating to the Developer section.
- Open image files in an embedded Pixlr editor.
- Edit images using Pixlr's robust editing tools.
- Handle real-time updates when images are saved in the editor.
- Easy integration with modern web applications.
- Tree-shakable and minimal bundle size.
Install Pixlr SDK via npm:
npm install @pixlrlte/pixlr-sdk
Or using yarn:
yarn add @pixlrlte/pixlr-sdk
Always generate the token server-side and never expose your API secret to the client.
To begin, ensure you have the necessary API access keys. You can generate them under /myaccount > Developer.
-
clientKey
: Your API key. -
clientSecret
: Your API secret, which should never be shared or exposed client-side.
These keys will be used to authenticate and generate a JWT (JSON Web Token) for secure API access.
This library offers a simple way to generate them using the class Token
and it's static method createToken
import { Token, type PixlrPayloadJWT } from 'pixlr-sdk';
const tokenService = new Token({
clientKey,
clientSecret,
});
const token = await tokenService.createToken(payload);
// Or if you want to use factory pattern:
const otherToken = await Token
.generate({ clientKey, clientSecret })
.createToken(payload);
The payload for the token generation depends on the API mode you are operating in, which can be either
http
orembedded
.
-
mode
: Specifies the API mode you are operating in (http
orembedded
). This property is required. -
settings
: An optional object that allows you to apply specific settings to Pixlr Applications. These settings can alter the behavior and theme of the applications without changing the API's behavior.
In embedded
mode, the payload requires the following properties:
-
mode
: "embedded" -
origin
: The base domain of your application (e.g.,https://yourdomain.com
). This is crucial for ensuring that Pixlr Applications respond only to requests originating from the specified domain.
Example:
const payload: PixlrPayloadJWT = {
mode: 'embedded',
origin: 'https://yourdomain.com',
settings: {
// Optional settings
}
};
In http mode, the payload includes these additional properties:
-
openUrl
: URL where the Pixlr Application will fetch and open an image on startup. Required in http mode. -
saveUrl
: URL where the Pixlr Applications will send a HTTP POST with the saved image. Required in http mode. -
follow
: Optional. If enabled (defaults to true), the application window will navigate to the saveUrl location using a standard FORM post. If disabled, it will POST using XHR, leaving the application window intact.
Example:
const payload: PixlrPayloadJWT = {
mode: 'http',
openUrl: '<https://example.com/open>',
saveUrl: '<https://example.com/save>',
follow: false, // Optional, defaults to true
settings: {
// Optional settings
}
};
The settings object in the payload allows for fine-tuning the Pixlr Applications' behavior and appearance. Available settings include:
-
referrer
: Name of the application using the API, displayed in the Pixlr Applications. -
icon
: URL to an icon for your application, shown in the Pixlr Applications. -
accent
: Accent color for the application. -
workspace
: Workspace (background) color for the application. -
tabLimit
: Maximum number of tabs a user can have open at once. -
blockOpen
: If true, Pixlr Application will block users from opening images from sources other than the API.
Example
settings: {
referrer: 'My Awesome App',
icon: 'https://example.com/icon.png',
accent: '#FF5733',
workspace: '#EEEEEE',
tabLimit: 5,
blockOpen: true
}
Connects to an instance of the Pixlr editor.
-
token
: JWT token for API access. -
target
: The iframe element to embed the editor in. -
options
: Optional. Open settings (not editor settings).-
baseUrl
: Optional url for the editor. Defaults tohttps://pixlr.com
. -
fullEditor
: Optional. By default a Pixlr Express version will be used, set this key to true to experiment the full power of Pixlr Editor. -
language
: Optional. By default Editor will be in English. Set this key to the preferred language
-
Opens an image file or url in the editor. Returns an async generator that yields updated files.
-
file
: The image file to open.
Here's a quick example to get you started:
import { Editor } from 'pixlr-sdk';
const frame = document.getElementById('your-iframe-id');
const fileInput = document.getElementById('your-file-input-id');
let editor;
fileInput.addEventListener('change', async (event) => {
const files = event.target.files;
if (files.length > 0) {
const file = files[0]; // Use the first file for this example
if(!editor) {
// Connect to the Pixlr editor
editor = await Editor.connect('your-jwt-token', frame, {
baseUrl: "https://pixlr.com", // Optional: Custom base URL for the editor
language: "jp", // Optional: Language for application
});
}
// Open the file in the editor
for await (const newFile of editor.open(file)) {
// Handle the updated file
// For example, display the edited image on your page
}
}
});
In your HTML:
<iframe id="your-iframe-id" src="/iframe/empty"></iframe>
<input type="file" id="your-file-input-id" />
-
Customization: Replace placeholders like
your-jwt-token
,your-iframe-id
,your-file-input-id
, and links (LINK_TO_YOUR_CONTRIBUTING_GUIDE
,LINK_TO_YOUR_LICENSE
) with actual values or paths relevant to your project. -
Additional Sections: Depending on your project's complexity and community involvement, you might want to add sections like 'Support', 'Roadmap', or 'Acknowledgments'.
-
Examples and Documentation: If your library has more complex use cases or configurations, consider adding a link to a more detailed documentation site or wiki. For larger examples, you might also include a separate
examples
folder in your project repository and reference it in the README. -
Issue Reporting and Code of Conduct: Encourage users to report issues via the issue tracker on your repository. It's also good practice to include a Code of Conduct to foster an inclusive and respectful community.
-
Versioning and Updates: If your library will undergo active development, mention how versioning will be handled, and how users can stay updated with new releases.
-
Demo or Live Example: If possible, provide a link to a live demo or a sandbox environment like CodeSandbox or JSFiddle. This allows users to see your library in action and try it out without any setup.
-
Screenshots or Videos: Visuals can be very helpful in showing users what to expect from your library. If your library has a UI component, consider adding screenshots or videos demonstrating its use.
-
Support or Contact Information: If you or your organization offers professional support, consultancy, or you just want to offer a way for users to reach out for help, include contact information or links to relevant resources.