Skip to content

quick-start.md

Latest commit

 

History

History
107 lines (80 loc) · 3.73 KB

quick-start.md

File metadata and controls

107 lines (80 loc) · 3.73 KB
Raw

Quick Start

This guide takes you from an installed PPTKit package to an editable .pptx file using the current pre-release API. It is for application developers; contributors should use the Developer Workflow.

Prerequisites

  • Node.js 20 or newer for the Node.js file-output example
  • PPTKit installed in your TypeScript or Node.js project; see Install PPTKit

Create and export a presentation

Save the following as quick-start.ts in a workspace package or another project configured to resolve the workspace packages.

import { createPresentation, validatePresentation } from "@pptkit/core";
import { writePptx } from "@pptkit/pptx-exporter/node";

const presentation = createPresentation({
  metadata: { title: "Hello PPTKit", author: "Example Team" },
  theme: { colors: { accent1: "2457D6" } },
});

const slide = presentation.addSlide();
slide.addElement({
  type: "text",
  content: [{
    runs: [
      { text: "Hello ", style: { fontSize: 36 } },
      {
        text: "PPTKit",
        style: { fontSize: 36, bold: true, color: { theme: "accent1" } },
      },
    ],
  }],
  box: { x: 64, y: 64, width: 520, height: 72 },
});

const diagnostics = validatePresentation(presentation);
if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
  throw new Error(JSON.stringify(diagnostics, null, 2));
}

const result = await writePptx(presentation, {
  output: "./hello-pptkit.pptx",
});

console.log(result.status, result.output, result.warnings);

Run it with your TypeScript runner or compile it with your project.

The Node exporter creates parent directories when necessary and returns:

  • status: written or written-with-warnings
  • output: the written path
  • slideCount and byteLength
  • warnings: recoverable asset-loading problems

Core validation errors are not warnings. writePptx() rejects with PresentationValidationError before packaging when the document is invalid.

The checked copy of this example lives at docs/examples/quick-start.ts. Contributors can run it with the command documented in the Developer Workflow.

Why the code uses methods

Slides and elements are inserted through methods so Core can own stable IDs and validate ordering. The exposed collections are readonly snapshots:

const second = presentation.addSlide();
second.addElement({
  type: "shape",
  shape: "roundRect",
  box: { x: 80, y: 120, width: 300, height: 160 },
  style: {
    fill: { type: "solid", color: { theme: "accent1" }, opacity: 0.15 },
    stroke: { paint: { type: "solid", color: { theme: "accent1" } }, width: 2 },
  },
});

Element order is drawing order. Use moveElement() instead of a zIndex field.

Browser generation

Browser-capable runtimes use the default exporter entry and receive bytes instead of writing a file:

import { generatePptx } from "@pptkit/pptx-exporter";

const result = await generatePptx(presentation);
const blob = new Blob([result.bytes], {
  type: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
});

The default entry loads URL assets. The Node entry additionally loads local path assets.

Next steps

  • Create Your First Deck adds layouts, placeholders, images, multiple slides, and error handling.
  • Core API documents every authoring method and input family.
  • Elements covers images, shapes, connectors, groups, and tables.
  • Themes and layouts explains inheritance and placeholders.
  • PPTX exporter documents runtime loading, results, warnings, and failures.