Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .changeset/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Changesets

This folder holds pending release notes for [`@powersync/docs-content`](../packages/docs-content/README.md). Docs authors don't add changesets. A maintainer adds one with `pnpm changeset` when they decide to release the package. See [Releasing](../packages/docs-content/README.md#releasing).
11 changes: 11 additions & 0 deletions .changeset/config.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
"changelog": "@changesets/cli/changelog",
"commit": false,
"fixed": [],
"linked": [],
"access": "public",
"baseBranch": "main",
"updateInternalDependencies": "patch",
"ignore": []
}
5 changes: 5 additions & 0 deletions .changeset/initial-release.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@powersync/docs-content': patch
---

Initial release: connector snippets, write path prompts, and write path diagrams from the PowerSync docs.
36 changes: 36 additions & 0 deletions .github/workflows/build-docs-content.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
name: Build Docs Content Package

# The package build fails if a connector snippet, prompt, or diagram it reads
# is missing or malformed, so run it whenever those sources change.
on:
pull_request:
paths:
- 'snippets/**'
- 'images/**'
- 'packages/**'
- 'pnpm-lock.yaml'
- 'pnpm-workspace.yaml'
- '.github/workflows/build-docs-content.yaml'

jobs:
build:
name: Build @powersync/docs-content
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4

- name: Enable Corepack
run: corepack enable

- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
cache: pnpm

- name: Install dependencies
run: pnpm install --frozen-lockfile

- name: Build package
run: pnpm --filter @powersync/docs-content build
45 changes: 45 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
name: Release

on:
push:
branches:
- main

concurrency: ${{ github.workflow }}-${{ github.ref }}

permissions:
id-token: write # Required for OIDC / trusted publishing
contents: write # Required for changesets pushing commits
pull-requests: write # Required for changesets creating PRs

jobs:
release:
name: Release
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
uses: actions/checkout@v4
with:
persist-credentials: false

- name: Enable Corepack
run: corepack enable

- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
cache: pnpm

- name: Install dependencies
run: pnpm install --frozen-lockfile

# With pending changesets, this opens or updates the Version Packages PR.
# When that PR is merged, there are none left and this publishes to npm.
- name: Create Release Pull Request or Publish to npm
uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0
with:
version: pnpm changeset:version
publish: pnpm release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
3 changes: 3 additions & 0 deletions .mintignore
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,6 @@ README.md

# Scheduled agent prompts
routines/

# npm packages built from the docs content
packages/
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ Skills, reviewer prompts, and generic Mintlify guidance do not override those st

- `docs.json`: navigation, theme, and redirects. Read before changing documentation.
- `*.mdx`: pages; `snippets/`: reusable components; `images/` and `logo/`: assets.
- `packages/docs-content/`: npm package of docs content for use outside the docs site, built from `snippets/backend-connectors/`, `snippets/write-path/*-prompt.mdx`, and `images/handling-writes/`. See [its README](packages/docs-content/README.md).
- `.vale.ini` and `.github/vale/`: prose lint rules and accepted vocabulary.
- `routines/`: versioned copies of cloud prompts; editing these files does not update a live routine.

Expand Down
2 changes: 2 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ Thanks for contributing to our documentation!

Once your PR is approved and merged to `main`, your changes will be automatically published to https://docs.powersync.com.

Files in `snippets/backend-connectors/`, `snippets/write-path/*-prompt.mdx`, and `images/handling-writes/` also feed the [`@powersync/docs-content`](/packages/docs-content/README.md) package, which the PowerSync Dashboard and other projects use. Maintainers release it separately.

## Getting Help

If you have questions or need help:
Expand Down
7 changes: 6 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,14 +1,19 @@
{
"name": "powersync-docs",
"version": "1.0.0",
"private": true,
"packageManager": "pnpm@11.3.0+sha512.2c403d6594527287672b1f7056343a1f7c3634036a67ffabfcc2b3d7595d843768f8787148d1b57cf7956c90606bbd192857c363af19e96d2d0ec9ec5741d215",
"scripts": {
"dev": "mint dev",
"format": "mint format",
"check:links": "node scripts/check-links.mjs",
"prepare": "husky"
"prepare": "husky",
"changeset": "changeset",
"changeset:version": "changeset version && pnpm install --lockfile-only --frozen-lockfile=false",
"release": "pnpm --filter @powersync/docs-content build && changeset publish"
},
"devDependencies": {
"@changesets/cli": "^2.31.1",
"husky": "^9.1.7",
"mint": "4.2.986"
}
Expand Down
3 changes: 3 additions & 0 deletions packages/docs-content/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
dist/
# Copied from the repository root by the build
LICENSE
40 changes: 40 additions & 0 deletions packages/docs-content/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# @powersync/docs-content

Connector snippets, agent prompts, and diagrams from the PowerSync docs, for use outside the docs site, such as in the PowerSync Dashboard.

The docs are the source of truth. The build reads:

- `snippets/backend-connectors/**/*.mdx`
- `snippets/write-path/*-prompt.mdx`
- `images/handling-writes/*.png`

To change the content, edit those files.

## Usage

```ts
import { CONNECTOR_URL_PLACEHOLDER, type ConnectorId } from '@powersync/docs-content';
import connector from '@powersync/docs-content/connectors/generic/typescript';
import prompt from '@powersync/docs-content/prompts/existing-api';
import diagram from '@powersync/docs-content/images/write-path-overview.png';

const code = connector.replace(CONNECTOR_URL_PLACEHOLDER, instanceUrl);
```

The root export also has `CONNECTOR_IDS`, `PROMPT_IDS`, and `IMAGE_IDS`.

Removing or renaming an ID, or changing the placeholder, is a breaking change.

## Local Development

```sh
pnpm --filter @powersync/docs-content build
```

To try it in another project, run `pnpm link <path-to-this-directory>` there, and rebuild after each change.

## Releasing

1. Run `pnpm changeset` and select `@powersync/docs-content`.
2. Merge to `main`. The Release workflow opens a Version Packages PR.
3. Merge that PR to publish to npm.
46 changes: 46 additions & 0 deletions packages/docs-content/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
{
"name": "@powersync/docs-content",
"version": "0.0.0",
Comment thread
Manrich121 marked this conversation as resolved.
Resolved
"description": "Connector snippets, agent prompts, and diagrams from the PowerSync docs.",
"type": "module",
"license": "FSL-1.1-ALv2",
"repository": {
"type": "git",
"url": "git+https://github.com/powersync-ja/powersync-docs.git",
"directory": "packages/docs-content"
},
"homepage": "https://github.com/powersync-ja/powersync-docs/tree/main/packages/docs-content#readme",
"files": [
"dist",
"LICENSE"
],
"sideEffects": false,
"types": "./dist/index.d.mts",
"exports": {
".": {
"types": "./dist/index.d.mts",
"default": "./dist/index.mjs"
},
"./connectors/*": {
"types": "./dist/connectors/*.d.mts",
"default": "./dist/connectors/*.mjs"
},
"./prompts/*": {
"types": "./dist/prompts/*.d.mts",
"default": "./dist/prompts/*.mjs"
},
"./images/*": "./dist/images/*",
"./package.json": "./package.json"
},
"scripts": {
"build": "node scripts/build.mjs",
"prepack": "node scripts/build.mjs"
},
"publishConfig": {
"access": "public",
"provenance": true
},
"engines": {
"node": ">=18"
}
}
Loading
Loading