@nomideusz/svelte-media 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,12 +1,42 @@
 # Changelog
 
+## 0.2.0 — 2026-08-03
+
+### Changed
+- **Breaking: the package is split into two entry points.** Storage adapters,
+  `processAndStore`, `deleteMedia` and `getMediaUrl` move to
+  `@nomideusz/svelte-media/server`; components, `validateImageFile`, the key
+  helpers, `IMAGE_SIZES` and the types stay on the root import.
+
+  Everything was previously behind one entry, and `core/process.ts` imported
+  `sharp` while `core/local-adapter.ts` imported `node:fs` and `node:path` at
+  module level. Any browser bundle that touched the package pulled those in and
+  failed to build — which means `ImageUpload` and `ImageGallery`, the two
+  exports that exist to be used from a component, could not be. The bug went
+  unnoticed because both apps in the source monorepo import only from server
+  files.
+
+  Migration: append `/server` to imports of the adapters or the pipeline. Key
+  helpers are re-exported from `/server` too, so a server file still needs one
+  import.
+
+### Added
+- A real demo at https://svelte-media-gamma.vercel.app/ — the components running
+  live, `validateImageFile` against files you choose, and the storage-key layout
+  for a prefix and entity you type. The server pipeline is shown as code, since
+  it cannot run in a browser.
+
+
 Backfilled 2026-08-02 from git history. Entries before that date are
 reconstructed from commits, so they record what changed rather than a release
-that was tagged at the time. The package has not been published to npm yet.
+that was tagged at the time. 0.1.0 was published manually — trusted publishing
+cannot bootstrap a package that does not exist yet — and releases from 0.1.1 on
+go through the repo's Release & Publish workflow.
 
-## Unreleased
+## 0.1.1 — 2026-08-03
 
 ### Added
+- Demo site at https://svelte-media-gamma.vercel.app/; `homepage` points at it.
 - README — the package's first, documenting the adapter seam, the four sizes,
   the `(prefix, entityId, filename)` key shape the helpers take, and the fact
   that all output is WebP regardless of what was uploaded.

package/README.md

@@ -10,9 +10,18 @@ pluggable storage adapter — S3-compatible or local disk.
 pnpm add @nomideusz/svelte-media
 ```
 
-> Requires Svelte 5 (`^5.0.0`). The processing path is server-only: it uses
-> `sharp` and Node `Buffer`. Import `processAndStore` from server code
-> (`+page.server.ts`, a route handler, a script) — never from a component.
+> Requires Svelte 5 (`^5.0.0`).
+
+The package has two entry points, because half of it cannot run in a browser:
+
+| Import | Contains | Where |
+|---|---|---|
+| `@nomideusz/svelte-media` | components, `validateImageFile`, key helpers, `IMAGE_SIZES`, types | anywhere |
+| `@nomideusz/svelte-media/server` | storage adapters, `processAndStore`, `deleteMedia`, `getMediaUrl` | server only |
+
+The pipeline needs `sharp`, `node:fs` and `Buffer`. Keeping it behind `/server`
+is what lets a component import `ImageUpload` without a bundler dragging those
+into the browser build.
 
 ## Why
 
@@ -24,7 +33,7 @@ the seam.
 ## Quick Start
 
 ```ts
-import { createS3Adapter, processAndStore, getMediaUrl } from '@nomideusz/svelte-media';
+import { createS3Adapter, processAndStore, getMediaUrl } from '@nomideusz/svelte-media/server';
 
 const storage = createS3Adapter({
   endpoint:        process.env.S3_ENDPOINT!,     // https://xxx.r2.cloudflarestorage.com
@@ -79,7 +88,7 @@ interface StorageAdapter {
 Two ship with the package:
 
 ```ts
-import { createS3Adapter, createLocalAdapter } from '@nomideusz/svelte-media';
+import { createS3Adapter, createLocalAdapter } from '@nomideusz/svelte-media/server';
 
 createS3Adapter({ /* S3Config, above */ });   // R2, MinIO, Tigris, AWS
 createLocalAdapter({ root: '/data/images' }); // writes under root, mkdir -p
@@ -109,7 +118,7 @@ is only needed to reject early and report a friendlier message.
 ## Deleting
 
 ```ts
-import { deleteMedia } from '@nomideusz/svelte-media';
+import { deleteMedia } from '@nomideusz/svelte-media/server';
 
 // Removes all four sizes; individual failures are swallowed
 await deleteMedia(storage, stored.prefix, stored.entityId, stored.filename);
@@ -152,23 +161,23 @@ the same reason: it renders on the client, where the adapter cannot go.
 ## API
 
 ```ts
-// Adapters
+// ── @nomideusz/svelte-media/server ──
 createS3Adapter(config: S3Config): StorageAdapter
 createLocalAdapter(config: LocalConfig): StorageAdapter
-
-// Pipeline
 processAndStore(adapter, file, prefix, entityId, config?): Promise<StoredMedia>
 deleteMedia(adapter, prefix, entityId, filename): Promise<void>
 getMediaUrl(adapter, prefix, entityId, filename, size = 'medium'): string
-getStorageKey(prefix, entityId, filename, size): string   // `${prefix}/${entityId}/${sizePrefix}${filename}`
+
+// ── @nomideusz/svelte-media (client-safe) ──
 validateImageFile(file, config?): ValidationResult
 generateMediaKey(): string                                 // `<cuid2>.webp`
+getStorageKey(prefix, entityId, filename, size): string   // `${prefix}/${entityId}/${sizePrefix}${filename}`
 IMAGE_SIZES
-
-// Components
 ImageUpload, ImageGallery
 ```
 
+Key helpers are exported from both entries, so server code needs only one import.
+
 Types: `StorageAdapter`, `S3Config`, `LocalConfig`, `StoredMedia`, `ImageSize`,
 `MediaConfig`, `ValidationResult`.
 

package/dist/core/media.d.ts

@@ -0,0 +1,25 @@
+import type { ImageSize, MediaConfig, ValidationResult } from './types.js';
+export declare const DEFAULT_MAX_SIZE: number;
+export declare const DEFAULT_ALLOWED_TYPES: string[];
+export declare const IMAGE_SIZES: {
+    thumbnail: {
+        width: number;
+        height: number;
+        fit: "cover";
+    };
+    medium: {
+        width: number;
+        height: number;
+        fit: "inside";
+    };
+    large: {
+        width: number;
+        height: number;
+        fit: "inside";
+    };
+};
+export declare const SIZE_PREFIXES: Record<ImageSize, string>;
+export declare const SIZE_QUALITY: Record<ImageSize, number>;
+export declare function validateImageFile(file: File, config?: MediaConfig): ValidationResult;
+export declare function generateMediaKey(_originalName?: string): string;
+export declare function getStorageKey(prefix: string, entityId: string, filename: string, size: ImageSize): string;

package/dist/core/media.js

@@ -0,0 +1,43 @@
+// Client-safe half of the package: validation, naming and key layout.
+// Deliberately free of sharp, node:fs and Buffer so components and browser code
+// can import it — see core/process.ts for the server pipeline.
+import { createId } from '@paralleldrive/cuid2';
+export const DEFAULT_MAX_SIZE = 5 * 1024 * 1024;
+export const DEFAULT_ALLOWED_TYPES = ['image/jpeg', 'image/jpg', 'image/png', 'image/webp'];
+export const IMAGE_SIZES = {
+    thumbnail: { width: 300, height: 300, fit: 'cover' },
+    medium: { width: 800, height: 600, fit: 'inside' },
+    large: { width: 1200, height: 900, fit: 'inside' },
+};
+export const SIZE_PREFIXES = {
+    original: '',
+    thumbnail: 'thumb_',
+    medium: 'med_',
+    large: 'large_',
+};
+export const SIZE_QUALITY = {
+    original: 95,
+    thumbnail: 80,
+    medium: 85,
+    large: 90,
+};
+export function validateImageFile(file, config) {
+    const maxSize = config?.maxFileSize ?? DEFAULT_MAX_SIZE;
+    const allowed = config?.allowedTypes ?? DEFAULT_ALLOWED_TYPES;
+    if (file.size > maxSize) {
+        const mb = Math.round(maxSize / 1024 / 1024);
+        return { valid: false, error: `File too large (max ${mb}MB)` };
+    }
+    if (!allowed.includes(file.type)) {
+        return { valid: false, error: `Invalid file type. Allowed: JPEG, PNG, WebP` };
+    }
+    return { valid: true };
+}
+export function generateMediaKey(_originalName) {
+    // All processed output is WebP regardless of the uploaded format.
+    return `${createId()}.webp`;
+}
+export function getStorageKey(prefix, entityId, filename, size) {
+    const sizePrefix = SIZE_PREFIXES[size];
+    return `${prefix}/${entityId}/${sizePrefix}${filename}`;
+}

package/dist/core/process.d.ts

@@ -1,24 +1,4 @@
-import type { StorageAdapter, StoredMedia, ImageSize, MediaConfig, ValidationResult } from './types.js';
-export declare const IMAGE_SIZES: {
-    thumbnail: {
-        width: number;
-        height: number;
-        fit: "cover";
-    };
-    medium: {
-        width: number;
-        height: number;
-        fit: "inside";
-    };
-    large: {
-        width: number;
-        height: number;
-        fit: "inside";
-    };
-};
-export declare function validateImageFile(file: File, config?: MediaConfig): ValidationResult;
-export declare function generateMediaKey(_originalName?: string): string;
-export declare function getStorageKey(prefix: string, entityId: string, filename: string, size: ImageSize): string;
+import type { StorageAdapter, StoredMedia, ImageSize, MediaConfig } from './types.js';
 export declare function processAndStore(adapter: StorageAdapter, file: File, prefix: string, entityId: string, config?: MediaConfig): Promise<StoredMedia>;
 export declare function deleteMedia(adapter: StorageAdapter, prefix: string, entityId: string, filename: string): Promise<void>;
 export declare function getMediaUrl(adapter: StorageAdapter, prefix: string, entityId: string, filename: string, size?: ImageSize): string;

package/dist/core/process.js

@@ -1,44 +1,8 @@
+// Server-only pipeline: needs sharp and Node's Buffer. Importing this from a
+// browser bundle will fail — the client-safe helpers live in core/media.ts and
+// are re-exported from the package root.
 import sharp from 'sharp';
-import { createId } from '@paralleldrive/cuid2';
-const DEFAULT_MAX_SIZE = 5 * 1024 * 1024;
-const DEFAULT_ALLOWED_TYPES = ['image/jpeg', 'image/jpg', 'image/png', 'image/webp'];
-export const IMAGE_SIZES = {
-    thumbnail: { width: 300, height: 300, fit: 'cover' },
-    medium: { width: 800, height: 600, fit: 'inside' },
-    large: { width: 1200, height: 900, fit: 'inside' },
-};
-const SIZE_PREFIXES = {
-    original: '',
-    thumbnail: 'thumb_',
-    medium: 'med_',
-    large: 'large_',
-};
-const SIZE_QUALITY = {
-    original: 95,
-    thumbnail: 80,
-    medium: 85,
-    large: 90,
-};
-export function validateImageFile(file, config) {
-    const maxSize = config?.maxFileSize ?? DEFAULT_MAX_SIZE;
-    const allowed = config?.allowedTypes ?? DEFAULT_ALLOWED_TYPES;
-    if (file.size > maxSize) {
-        const mb = Math.round(maxSize / 1024 / 1024);
-        return { valid: false, error: `File too large (max ${mb}MB)` };
-    }
-    if (!allowed.includes(file.type)) {
-        return { valid: false, error: `Invalid file type. Allowed: JPEG, PNG, WebP` };
-    }
-    return { valid: true };
-}
-export function generateMediaKey(_originalName) {
-    // All processed output is WebP regardless of the uploaded format.
-    return `${createId()}.webp`;
-}
-export function getStorageKey(prefix, entityId, filename, size) {
-    const sizePrefix = SIZE_PREFIXES[size];
-    return `${prefix}/${entityId}/${sizePrefix}${filename}`;
-}
+import { IMAGE_SIZES, SIZE_QUALITY, generateMediaKey, getStorageKey, validateImageFile, } from './media.js';
 export async function processAndStore(adapter, file, prefix, entityId, config) {
     const validation = validateImageFile(file, config);
     if (!validation.valid)

package/dist/index.d.ts

@@ -1,7 +1,4 @@
 export type { StorageAdapter, S3Config, StoredMedia, ImageSize, MediaConfig, ValidationResult, } from './core/types.js';
-export type { LocalConfig } from './core/local-adapter.js';
-export { createS3Adapter } from './core/adapter.js';
-export { createLocalAdapter } from './core/local-adapter.js';
-export { validateImageFile, generateMediaKey, getStorageKey, processAndStore, deleteMedia, getMediaUrl, IMAGE_SIZES, } from './core/process.js';
+export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, DEFAULT_MAX_SIZE, DEFAULT_ALLOWED_TYPES, } from './core/media.js';
 export { default as ImageUpload } from './components/ImageUpload.svelte';
 export { default as ImageGallery } from './components/ImageGallery.svelte';

package/dist/index.js

@@ -1,5 +1,6 @@
-export { createS3Adapter } from './core/adapter.js';
-export { createLocalAdapter } from './core/local-adapter.js';
-export { validateImageFile, generateMediaKey, getStorageKey, processAndStore, deleteMedia, getMediaUrl, IMAGE_SIZES, } from './core/process.js';
+// Client-safe entry. The image pipeline and storage adapters need sharp,
+// node:fs and Buffer, so they live behind '@nomideusz/svelte-media/server' —
+// importing them here would break any browser bundle that touches a component.
+export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, DEFAULT_MAX_SIZE, DEFAULT_ALLOWED_TYPES, } from './core/media.js';
 export { default as ImageUpload } from './components/ImageUpload.svelte';
 export { default as ImageGallery } from './components/ImageGallery.svelte';

package/dist/server/index.d.ts

@@ -0,0 +1,6 @@
+export type { LocalConfig } from '../core/local-adapter.js';
+export { createS3Adapter } from '../core/adapter.js';
+export { createLocalAdapter } from '../core/local-adapter.js';
+export { processAndStore, deleteMedia, getMediaUrl } from '../core/process.js';
+export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, } from '../core/media.js';
+export type * from '../core/types.js';

package/dist/server/index.js

@@ -0,0 +1,6 @@
+// Server-only entry: sharp, node:fs and Buffer live behind here.
+export { createS3Adapter } from '../core/adapter.js';
+export { createLocalAdapter } from '../core/local-adapter.js';
+export { processAndStore, deleteMedia, getMediaUrl } from '../core/process.js';
+// Re-exported so server code needs only one import.
+export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, } from '../core/media.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomideusz/svelte-media",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Image upload, processing, and S3-compatible storage for Svelte 5 apps.",
   "type": "module",
   "sideEffects": false,
@@ -12,6 +12,10 @@
       "types": "./dist/index.d.ts",
       "svelte": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
     }
   },
   "files": [
@@ -64,5 +68,6 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/nomideusz/svelte-media"
-  }
+  },
+  "homepage": "https://svelte-media-gamma.vercel.app/"
 }