Skip to content

Commit 50ab557

Browse files
jumskijumski
authored
feat: add multi-target build support for @pgflow/client (#157)
* chore: update package.json module entry, enhance project build configuration, and refine Vite config - Changed package.json import and default entries for correct module resolution - Added build and typecheck targets with dependencies and output options in project.json - Updated Vite config to generate both ES and CJS formats, externalize dependencies, and improve build settings - Removed redundant export default statement from Vite config for clarity and correctness * chore: add browser test HTML, update package and build configs, and introduce Vite browser build * chore: update package.json exports and files, improve Vite build configuration with environment-based minification - Added files array to package.json for better package management - Updated exports to include default and browser entries - Modified Vite config to conditionally minify in production mode - Preserved build artifacts and source maps for development and production * chore: update package.json to set private to false and add publishConfig for public access - Changed "private" from true to false to enable publishing - Added "publishConfig" with access set to "public" for proper package publication * feat: add multi-target build support for @pgflow/client package - Enable builds for Node.js (ESM and CJS), browsers, and bundlers - Include full TypeScript declarations and CDN support - Add production minified builds with tree-shaking support * chore: remove redundant configuration options and enforce minification in Vite build - Removed obsolete "configurations" section from project.json - Updated Vite config to always minify with terser in production mode - Ensured consistent build settings and preserved library build directory * chore: add comprehensive build and release documentation for @pgflow/client - Introduced BUILD_AND_RELEASE.md detailing build outputs, configurations, usage, and local build commands - Updated README.md to reference the new build guide for detailed information on build process and formats * docs: add security notice and update permissions guidance in README and create SECURITY.md - Added a security warning to the README about minimal security controls - Replaced detailed schema permission SQL with a general note on proper permissions - Introduced a new SECURITY.md file outlining current security model, permissions, and future plans - Clarified current limitations and roadmap for security enhancements - Improved documentation clarity on security considerations and configuration steps * docs: update security notice and usage instructions in README and SECURITY.md - Clarify that pgflow currently lacks security features and is an MVP - Emphasize responsibility for securing schemas, tables, and functions - Add detailed permission grants and security considerations - Improve guidance on exposing schemas and implementing security controls - Update security documentation to reflect current limitations and best practices * docs: update README with security notice and import example; add FlowStepStatus import for step status handling * docs: update security notices and guidance for pgflow client and server - Clarify that pgflow currently ships with no permissions granted and emphasize the responsibility of users to implement security controls. - Add warnings about broad permission grants and recommend backend-only access approaches for production. - Provide detailed instructions for implementing row-level security policies, including schema modifications and policy examples. - Include guidance on tracking user attribution for security purposes. - Correct links to the project's discussions and clarify the security-related content. * chore: add terser dependency and update tsconfig include paths - Included terser in package.json for build optimization - Updated tsconfig.json to specify include paths and add compilerOptions * chore: update project configuration with main and outputPath in build options - Added "main" and "outputPath" properties to the build options in project.json - Ensured proper build output configuration for the client package * chore: update dependencies and documentation to include supabase-js - Correct installation command in README.md to install @pgflow/client - Add @supabase/supabase-js as a runtime dependency in client package.json - Remove duplicate @supabase/supabase-js dependency from devDependencies - Update core package.json to standardize supabase dependency version to 2.21.1 * feat: add multi-target build support for @pgflow/client and update dependencies - Enable building @pgflow/client for multiple environments including CommonJS, ESM, and browser - Add CDN support via unpkg with proper initialization instructions - Include all runtime dependencies in the browser build, excluding peer dependencies - Update documentation to reflect new build formats and usage instructions - Pin @supabase/supabase-js to a specific version for consistent type generation - Modify build and release instructions accordingly * chore: pnpm-lock.yaml * feat: update documentation and browser entry for improved client support - Clarify multi-environment build support in README and changelog - Add browser usage example with createClient factory function - Export createClient in browser.ts for easier client instantiation - Introduce browser-specific tests for createClient and PgflowClient - Add HTML test page for verifying global variables and client creation in browser build - Update Vite config to set global variable name to 'pgflow' for browser bundle
1 parent cdb5b04 commit 50ab557

15 files changed

+640
-110
lines changed

‎.changeset/fresh-zoos-arrive.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
'@pgflow/client': patch
3+
'@pgflow/core': patch
4+
---
5+
6+
feat: add multi-target build support for @pgflow/client package
7+
8+
The @pgflow/client package now builds for multiple environments, making it usable in Node.js, browsers, and bundlers.
9+
10+
**What's new:**
11+
12+
- ES modules (`.js`) and CommonJS (`.cjs`) builds for Node.js
13+
- Browser bundle (`.browser.js`) with all dependencies included
14+
- Full TypeScript declarations
15+
- CDN support via unpkg
16+
- Production builds with minification
17+
- Proper tree-shaking support
18+
- `@supabase/supabase-js` is now a regular dependency (not peer dependency)
19+
20+
**You can now use it in:**
21+
22+
- Node.js: `import { PgflowClient } from '@pgflow/client'`
23+
- CommonJS: `const { PgflowClient } = require('@pgflow/client')`
24+
- Browser: `<script src="https://unpkg.com/@pgflow/client"></script>` - then use `window.pgflow.createClient(supabase)`
25+
- Bundlers: Automatically picks the right format
26+
27+
**Other changes:**
28+
29+
- Pin Supabase CLI to exact version 2.21.1 to ensure consistent type generation between local and CI environments

‎pkgs/client/BUILD_AND_RELEASE.md

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Build and Release Guide for @pgflow/client
2+
3+
This document explains how @pgflow/client is built and distributed for different environments.
4+
5+
## Build Outputs
6+
7+
The package is built in multiple formats to support various JavaScript environments:
8+
9+
### Node.js Builds
10+
- **ES Module** (`dist/index.js`) - Modern JavaScript modules using `import/export`
11+
- **CommonJS** (`dist/index.cjs`) - Legacy Node.js format using `require()`
12+
- Both formats exclude dependencies (they are installed automatically via npm)
13+
- Not minified - allows bundlers to optimize as needed
14+
15+
### Browser Build
16+
- **IIFE Bundle** (`dist/pgflow-client.browser.js`) - Browser-ready build
17+
- Includes all dependencies EXCEPT @supabase/supabase-js
18+
- Expects users to provide their own Supabase client instance
19+
- Exposes `window.pgflow` global variable with factory functions
20+
- Always minified with terser for optimal file size (16KB gzipped: 4.3KB)
21+
- Includes source maps for debugging
22+
23+
### TypeScript Declarations
24+
- Full type definitions in `dist/src/` directory
25+
- Main entry point at `dist/index.d.ts`
26+
- Preserves complete type information for all exports
27+
28+
## Build Configuration
29+
30+
The build uses two Vite configurations:
31+
32+
1. **vite.config.ts** - Library builds (ES and CJS)
33+
- External dependencies for smaller bundle size
34+
- Generates TypeScript declarations with vite-plugin-dts
35+
- No minification - lets consumer's bundler handle it
36+
37+
2. **vite.browser.config.ts** - Browser build
38+
- Bundles all dependencies
39+
- IIFE format for direct browser usage
40+
- Always minified for production use
41+
42+
## Usage in Different Environments
43+
44+
### NPM Package
45+
```bash
46+
npm install @pgflow/client
47+
```
48+
49+
```javascript
50+
// ES Modules (recommended)
51+
import { PgflowClient } from '@pgflow/client';
52+
53+
// CommonJS
54+
const { PgflowClient } = require('@pgflow/client');
55+
```
56+
57+
### Browser via CDN
58+
```html
59+
<!-- First, load Supabase (required) -->
60+
<script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>
61+
62+
<!-- Then load pgflow client -->
63+
<script src="https://unpkg.com/@pgflow/client"></script>
64+
65+
<script>
66+
// Initialize Supabase (you already have this)
67+
const supabase = window.supabase.createClient('your-url', 'your-anon-key');
68+
69+
// Create pgflow client using the factory function
70+
const pgflow = window.pgflow.createClient(supabase);
71+
</script>
72+
```
73+
74+
### Modern Bundlers
75+
Bundlers like Webpack, Vite, and Rollup will automatically select the appropriate format:
76+
- Browsers: Uses the browser build when `browser` condition is set
77+
- Node.js: Uses ES modules for tree-shaking
78+
- Fallback: CommonJS for compatibility
79+
80+
## Package.json Configuration
81+
82+
The package.json uses modern packaging standards:
83+
84+
```json
85+
{
86+
"exports": {
87+
".": {
88+
"browser": "./dist/pgflow-client.browser.js",
89+
"types": "./dist/index.d.ts",
90+
"import": "./dist/index.js",
91+
"require": "./dist/index.cjs",
92+
"default": "./dist/index.js"
93+
}
94+
},
95+
"unpkg": "./dist/pgflow-client.browser.js",
96+
"files": ["dist/**/*", "README.md", "LICENSE", "CHANGELOG.md"]
97+
}
98+
```
99+
100+
- **exports**: Conditional exports for different environments
101+
- **unpkg**: CDN entry point for browsers
102+
- **files**: Only necessary files included in npm package
103+
104+
## Building Locally
105+
106+
```bash
107+
# Build all formats
108+
pnpm nx build client
109+
110+
# Build only library formats
111+
pnpm nx build:lib client
112+
113+
# Build only browser format
114+
pnpm nx build:browser client
115+
```
116+
117+
## Dependencies
118+
119+
- **Runtime**: @pgflow/core, @pgflow/dsl, @supabase/supabase-js, nanoevents, uuid
120+
121+
All runtime dependencies are automatically installed when you install @pgflow/client. The browser build includes all these dependencies bundled together.

‎pkgs/client/CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828

2929
```typescript
3030
// Start a workflow
31+
import { PgflowClient } from '@pgflow/client';
3132
const pgflow = new PgflowClient(supabase);
3233
const run = await pgflow.startFlow('analyze_website', {
3334
url: 'https://example.com',

0 commit comments

Comments
 (0)