solidstep 0.3.5 → 0.4.0

package/README.md

@@ -37,6 +37,7 @@ cd my-app
 - `not-found.tsx` - 404 page (root only - optional)
 - `route.ts` - API route handler
 - `middleware.ts` - Request middleware
+- `instrumentation.ts` - Server instrumentation hooks (optional)
 
 **A route is defined by either the presence of a `page.tsx` or `route.ts` file in a directory.**
 
@@ -274,6 +275,111 @@ function CreatePostForm() {
 }
 ```
 
+### Form Actions
+
+Use the `<Form>` component to submit forms via server actions — similar to Next.js form handling:
+
+```tsx
+// app/invoices/actions.ts
+'use server';
+
+export async function createInvoice(formData: FormData) {
+  const rawFormData = {
+    customerId: formData.get('customerId'),
+    amount: formData.get('amount'),
+    status: formData.get('status'),
+  };
+  // mutate data, revalidate cache
+}
+```
+
+```tsx
+// app/invoices/page.tsx
+import { Form } from 'solidstep/form';
+import { createInvoice } from './actions';
+
+export default function Page() {
+  return (
+    <Form action={createInvoice}>
+      <input name="customerId" />
+      <input name="amount" type="number" />
+      <select name="status">
+        <option value="pending">Pending</option>
+        <option value="paid">Paid</option>
+      </select>
+      <button type="submit">Create Invoice</button>
+    </Form>
+  );
+}
+```
+
+**Passing additional arguments with `bind`:**
+
+```tsx
+import { Form } from 'solidstep/form';
+import { updateUser } from './actions';
+
+export function UserProfile(props: { userId: string }) {
+  const updateUserWithId = updateUser.bind(null, props.userId);
+
+  return (
+    <Form action={updateUserWithId}>
+      <input type="text" name="name" />
+      <button type="submit">Update User Name</button>
+    </Form>
+  );
+}
+```
+
+**Form validation with `useActionState`:**
+
+```tsx
+import { useActionState } from 'solidstep/hooks/action-state';
+import { Form } from 'solidstep/form';
+import { signup } from './actions';
+
+export function SignupForm() {
+  const [state, formAction, pending, error] = useActionState(signup, {
+    errors: {} as Record<string, string[]>,
+    message: '',
+  });
+
+  return (
+    <Form action={formAction}>
+      <label for="email">Email</label>
+      <input type="email" id="email" name="email" required />
+      {state().errors.email && <span>{state().errors.email[0]}</span>}
+      <p aria-live="polite">{state().message}</p>
+      {error() && <p role="alert" style="color:red">{error()!.message}</p>}
+      <button disabled={pending()}>
+        {pending() ? 'Signing up...' : 'Sign up'}
+      </button>
+    </Form>
+  );
+}
+```
+
+**Pending state with `useFormStatus`:**
+
+```tsx
+import { useFormStatus } from 'solidstep/hooks/form-status';
+
+export function SubmitButton() {
+  const { pending } = useFormStatus();
+
+  return (
+    <button disabled={pending()} type="submit">
+      {pending() ? 'Submitting...' : 'Submit'}
+    </button>
+  );
+}
+```
+
+> **Good to know:**
+> - `<Form>` supports progressive enhancement — when JS is disabled, forms submit natively to the server action endpoint.
+> - `useActionState` returns SolidJS accessors: call `state()`, `pending()`, and `error()` to read values. `error()` is `null` until the action throws, and resets to `null` on the next submission.
+> - `useFormStatus` must be used in a component nested inside `<Form>`.
+
 ### Metadata
 
 Define metadata for SEO:
@@ -341,16 +447,138 @@ export const generateMeta = meta(() => {
 
 ### Middleware
 
-Intercept and modify requests:
+Intercept and modify requests. SolidStep's `defineMiddleware` composes an ordered array of middleware units into a single handler, so you can keep concerns (auth, CORS, CSRF, logging) in separate, reusable pieces:
+
+```tsx
+// app/middleware.ts
+import { defineMiddleware, type Middleware } from 'solidstep/utils/middleware';
+
+const logger: Middleware = {
+  onRequest: (event) => {
+    console.log('Incoming request:', event.path);
+  },
+};
+
+const auth: Middleware = {
+  onRequest: (event) => {
+    if (!event.headers.get('authorization')) {
+      // Return a Response to short-circuit — later middleware and the
+      // route handler are skipped.
+      return new Response('Unauthorized', { status: 401 });
+    }
+  },
+};
+
+export default defineMiddleware([logger, auth]);
+```
+
+- `onRequest` hooks run in array order and stop as soon as one returns a `Response` (or calls `event.respondWith(...)`).
+- `onBeforeResponse` hooks always all run, in array order, and receive the resolved response so it can be inspected or mutated.
+
+You can still use Vinxi's own single-object form from `vinxi/http` if you prefer:
 
 ```tsx
 import { defineMiddleware } from 'vinxi/http';
 
 export default defineMiddleware({
-  onRequest: async (request) => {
-    console.log('Incoming request:', request.url);
-    // Modify request if needed
-    return request;
+  onRequest: (event) => {
+    console.log('Incoming request:', event.path);
+  },
+});
+```
+
+### Instrumentation
+
+SolidStep provides a server-side instrumentation API for observability, telemetry, and error tracking. Create an `app/instrumentation.ts` file to hook into the request lifecycle — no configuration required.
+
+```tsx
+// app/instrumentation.ts
+import { defineInstrumentation } from 'solidstep/utils/instrumentation';
+
+export default defineInstrumentation({
+  async register() {
+    // Called once at server startup.
+    // Initialize your telemetry SDK here (e.g., OpenTelemetry, Sentry).
+    console.log('[instrumentation] Server starting...');
+  },
+
+  async onRequest(request, context) {
+    // Called before each request is processed.
+    context.metadata.requestId = crypto.randomUUID();
+    console.log(`[instrumentation] ${request.method} ${context.pathname} (${context.routeType})`);
+  },
+
+  async onResponseEnd(request, context) {
+    // Called after the response is complete.
+    console.log(`[instrumentation] ${context.statusCode} ${context.pathname} ${context.duration.toFixed(1)}ms`);
+  },
+
+  async onRequestError(error, request, context) {
+    // Called when an unhandled error occurs during request processing.
+    console.error(`[instrumentation] Error in ${context.pathname}:`, error.message);
+  },
+});
+```
+
+**Available Hooks:**
+
+| Hook | When it fires | Arguments |
+|------|--------------|-----------|
+| `register` | Once at server startup | None |
+| `onRequest` | Before each request | `(request: Request, context: RequestContext)` |
+| `onResponseStart` | When response is ready, before streaming | `(request: Request, response: Response, context: ResponseContext)` |
+| `onResponseEnd` | After response stream is complete | `(request: Request, context: ResponseContext)` |
+| `onRequestError` | When an unhandled error occurs | `(error: Error, context: RequestContext)` |
+
+**Context Objects:**
+
+- `RequestContext` — includes `routePath`, `pathname`, `routeType` (`'page'` | `'api'` | `'server-action'` | `'not-found'`), `params`, `searchParams`, `startTime`, `startTimeEpoch`, and `metadata`
+- `ResponseContext` — extends `RequestContext` with `statusCode` and `duration` (ms)
+- `metadata` — a mutable `Record<string, unknown>` shared across all hooks for the same request. Use it to pass data between hooks (e.g., OpenTelemetry spans, request IDs).
+
+**Key Behaviors:**
+- Zero-config: if `app/instrumentation.ts` doesn't exist, the framework silently uses a no-op fallback
+- `register()` completes before the first request is handled
+- Errors in hooks are caught and logged — they never crash user requests
+- Works with page routes, API routes, and server actions
+- Compatible with OpenTelemetry, Sentry, Datadog, and any Node.js telemetry SDK
+
+**OpenTelemetry Example:**
+
+```tsx
+// app/instrumentation.ts
+import { defineInstrumentation } from 'solidstep/utils/instrumentation';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { trace } from '@opentelemetry/api';
+
+let sdk: NodeSDK;
+
+export default defineInstrumentation({
+  async register() {
+    sdk = new NodeSDK({
+      traceExporter: new OTLPTraceExporter(),
+      serviceName: 'my-solidstep-app',
+    });
+    sdk.start();
+  },
+
+  async onRequest(request, context) {
+    const tracer = trace.getTracer('solidstep');
+    const span = tracer.startSpan(`${request.method} ${context.routePath}`);
+    context.metadata.span = span;
+  },
+
+  async onResponseEnd(request, context) {
+    const span = context.metadata.span as any;
+    span?.setAttribute('http.status_code', context.statusCode);
+    span?.end();
+  },
+
+  async onRequestError(error, request, context) {
+    const span = context.metadata.span as any;
+    span?.recordException(error);
+    span?.end();
   },
 });
 ```
@@ -833,8 +1061,10 @@ const MyComponent: Component = () => {
 As SolidStep is built using Vite, it follows the same guide as stated in [Vite docs](https://vite.dev/guide/env-and-mode) regarding environment variables.
 
 ## Future Plans
+- Pre-rendering static pages at build time and partial pre-rendering for dynamic pages
 - Support for dynamic site.webmanifest, robots.txt, sitemap.xml, manifest.json, and llms.txt
 - Support loading and error pages for parallel routes
+- Support caching loaders
 - Support deferring loaders
 - Possible SSG, ISR, and PPR
 - Advanced caching strategies

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAUxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAGzC,KAAK,sBAAsB,GAAG,IAAI,CAC9B,YAAY,CAAC,QAAQ,CAAC,EACtB,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,gBAAgB,GAAG,MAAM,CAC7D,CAAC;AAEF,KAAK,sBAAsB,GAAG,kBAAkB,GAAG;IAC/C,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACnC,CAAC;AAEF,KAAK,MAAM,GAAG;IACV,MAAM,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE;QACN,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;QACnC,MAAM,EAAE,GAAG,CAAC;KACf,EAAE,CAAC;IACJ,MAAM,CAAC,EAAE,IAAI,GAAG,aAAa,CAAC;IAC9B,IAAI,CAAC,EACC,sBAAsB,GACtB,CAAC,CAAC,OAAO,EAAE;QACT,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;KAC/B,KAAK,sBAAsB,CAAC,CAAC;CACrC,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,SAAQ,MAIpC,wBAsHA,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAUxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAGzC,KAAK,sBAAsB,GAAG,IAAI,CAC9B,YAAY,CAAC,QAAQ,CAAC,EACtB,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,gBAAgB,GAAG,MAAM,CAC7D,CAAC;AAEF,KAAK,sBAAsB,GAAG,kBAAkB,GAAG;IAC/C,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACnC,CAAC;AAEF,KAAK,MAAM,GAAG;IACV,MAAM,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE;QACN,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;QACnC,MAAM,EAAE,GAAG,CAAC;KACf,EAAE,CAAC;IACJ,MAAM,CAAC,EAAE,IAAI,GAAG,aAAa,CAAC;IAC9B,IAAI,CAAC,EACC,sBAAsB,GACtB,CAAC,CAAC,OAAO,EAAE;QACT,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;KAC/B,KAAK,sBAAsB,CAAC,CAAC;CACrC,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,SAAQ,MAIpC,wBAqIA,CAAC"}

package/index.js

@@ -22,9 +22,9 @@ export const defineConfig = (config = {
     };
     // @ts-ignore
     globalThis.__SOLIDSTEP_CONFIG__ = sharedConfig;
-    const viteConfig = typeof config.vite === 'function'
+    const viteConfig = (typeof config.vite === 'function'
         ? config.vite
-        : () => config.vite || {};
+        : () => config.vite || {});
     const app = createApp({
         server: {
             ...config.server,
@@ -77,7 +77,24 @@ export const defineConfig = (config = {
                     serverFunctions.server(),
                     solid({ ssr: true }),
                     viteConfigPlugin('app-server', {
-                        ...(viteConfig({ router: 'server' }) || {}),
+                        resolve: {
+                            alias: {
+                                instrumentation: (() => {
+                                    const userInstrumentationTs = join(process.cwd(), 'app', 'instrumentation.ts');
+                                    const userInstrumentationJs = join(process.cwd(), 'app', 'instrumentation.js');
+                                    if (existsSync(userInstrumentationTs)) {
+                                        return userInstrumentationTs;
+                                    }
+                                    else if (existsSync(userInstrumentationJs)) {
+                                        return userInstrumentationJs;
+                                    }
+                                    else {
+                                        return normalize(fileURLToPath(new URL('./utils/instrumentation-noop.js', import.meta.url)));
+                                    }
+                                })(),
+                                ...(viteConfig({ router: 'server' })?.resolve?.alias || {}),
+                            },
+                        },
                     }),
                 ],
                 middleware: './app/middleware.ts',

package/package.json

@@ -1,72 +1,143 @@
-{
-    "name": "solidstep",
-    "version": "0.3.5",
-    "description": "Next Step SolidJS Framework for building web applications.",
-    "type": "module",
-    "author": "HamzaKV <hamzakv333@gmail.com>",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/HamzaKV/solidstep.git"
-    },
-    "license": "MIT",
-    "exports": {
-        ".": "./index.js",
-        "./hooks/action-state": "./utils/hooks/action-state.js",
-        "./utils/cache": "./utils/cache.js",
-        "./utils/client-only": "./utils/client-only.js",
-        "./utils/cookies": "./utils/cookies.js",
-        "./utils/cors": "./utils/cors.js",
-        "./utils/csp": "./utils/csp.js",
-        "./utils/csrf": "./utils/csrf.js",
-        "./utils/error-handler": "./utils/error-handler.js",
-        "./utils/fetch.client": "./utils/fetch.client.js",
-        "./utils/fetch.server": "./utils/fetch.server.js",
-        "./utils/loader": "./utils/loader.js",
-        "./utils/logger": "./utils/logger.js",
-        "./utils/meta": "./utils/meta.js",
-        "./utils/options": "./utils/options.js",
-        "./utils/redirect": "./utils/redirect.js",
-        "./utils/server-only": "./utils/server-only.js"
-    },
-    "scripts": {
-        "clean": "rimraf ./dist",
-        "copy-files:root": "copyfiles -u 0 README.md package.json generate/**/* LICENSE ./dist",
-        "build": "pnpm clean && tsc && pnpm copy-files:root",
-        "test:local": "pnpm build && cd ./dist && pnpm link --global",
-        "test:local:clean": "pnpm unlink && pnpm clean",
-        "roll": "pnpm build && cd dist && npm publish"
-    },
-    "keywords": [
-        "solidjs",
-        "web-development",
-        "typescript",
-        "npm",
-        "solidstep",
-        "framework"
-    ],
-    "dependencies": {
-        "@vinxi/server-functions": "0.5.1",
-        "pino": "^10.1.0",
-        "seroval": "^1.3.2",
-        "seroval-plugins": "^1.3.2",
-        "undici": "^7.15.0",
-        "vite-plugin-solid": "^2.11.7"
-    },
-    "devDependencies": {
-        "copyfiles": "^2.4.1",
-        "rimraf": "^6.0.1",
-        "solid-js": "^1.9.7",
-        "typescript": "^5.8.3",
-        "vinxi": "^0.5.8"
-    },
-    "peerDependencies": {
-        "solid-js": "^1.9.7",
-        "vinxi": "^0.5.8"
-    },
-    "engines": {
-        "node": ">=20"
-    },
-    "publishConfig": {
-        "access": "public"
-    }
-}
+{
+    "name": "solidstep",
+    "version": "0.4.0",
+    "description": "Next Step SolidJS Framework for building web applications.",
+    "type": "module",
+    "author": "HamzaKV <hamzakv333@gmail.com>",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/HamzaKV/solidstep.git"
+    },
+    "license": "MIT",
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "default": "./index.js"
+        },
+        "./hooks/action-state": {
+            "types": "./utils/hooks/action-state.d.ts",
+            "default": "./utils/hooks/action-state.js"
+        },
+        "./form": {
+            "types": "./utils/components/form.d.ts",
+            "default": "./utils/components/form.js"
+        },
+        "./hooks/form-status": {
+            "types": "./utils/hooks/form-status.d.ts",
+            "default": "./utils/hooks/form-status.js"
+        },
+        "./utils/cache": {
+            "types": "./utils/cache.d.ts",
+            "default": "./utils/cache.js"
+        },
+        "./utils/client-only": {
+            "types": "./utils/client-only.d.ts",
+            "default": "./utils/client-only.js"
+        },
+        "./utils/cookies": {
+            "types": "./utils/cookies.d.ts",
+            "default": "./utils/cookies.js"
+        },
+        "./utils/cors": {
+            "types": "./utils/cors.d.ts",
+            "default": "./utils/cors.js"
+        },
+        "./utils/csp": {
+            "types": "./utils/csp.d.ts",
+            "default": "./utils/csp.js"
+        },
+        "./utils/csrf": {
+            "types": "./utils/csrf.d.ts",
+            "default": "./utils/csrf.js"
+        },
+        "./utils/error-handler": {
+            "types": "./utils/error-handler.d.ts",
+            "default": "./utils/error-handler.js"
+        },
+        "./utils/fetch.client": {
+            "types": "./utils/fetch.client.d.ts",
+            "default": "./utils/fetch.client.js"
+        },
+        "./utils/fetch.server": {
+            "types": "./utils/fetch.server.d.ts",
+            "default": "./utils/fetch.server.js"
+        },
+        "./utils/instrumentation": {
+            "types": "./utils/instrumentation.d.ts",
+            "default": "./utils/instrumentation.js"
+        },
+        "./utils/loader": {
+            "types": "./utils/loader.d.ts",
+            "default": "./utils/loader.js"
+        },
+        "./utils/logger": {
+            "types": "./utils/logger.d.ts",
+            "default": "./utils/logger.js"
+        },
+        "./utils/meta": {
+            "types": "./utils/meta.d.ts",
+            "default": "./utils/meta.js"
+        },
+        "./utils/middleware": {
+            "types": "./utils/middleware.d.ts",
+            "default": "./utils/middleware.js"
+        },
+        "./utils/options": {
+            "types": "./utils/options.d.ts",
+            "default": "./utils/options.js"
+        },
+        "./utils/redirect": {
+            "types": "./utils/redirect.d.ts",
+            "default": "./utils/redirect.js"
+        },
+        "./utils/server-only": {
+            "types": "./utils/server-only.d.ts",
+            "default": "./utils/server-only.js"
+        }
+    },
+    "scripts": {
+        "clean": "rimraf ./dist",
+        "copy-files:root": "copyfiles -u 0 README.md package.json generate/**/* LICENSE ./dist",
+        "build": "pnpm clean && tsc && pnpm copy-files:root",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:local": "pnpm build && cd ./dist && pnpm link --global",
+        "test:local:clean": "pnpm unlink && pnpm clean",
+        "roll": "pnpm build && cd dist && npm publish"
+    },
+    "keywords": [
+        "solidjs",
+        "web-development",
+        "typescript",
+        "npm",
+        "solidstep",
+        "framework"
+    ],
+    "dependencies": {
+        "@vinxi/server-functions": "0.5.1",
+        "pino": "^10.1.0",
+        "seroval": "^1.3.2",
+        "seroval-plugins": "^1.3.2",
+        "undici": "^7.15.0",
+        "vite-plugin-solid": "^2.11.7"
+    },
+    "devDependencies": {
+        "@vitest/coverage-v8": "^4.1.8",
+        "copyfiles": "^2.4.1",
+        "rimraf": "^6.0.1",
+        "solid-js": "^1.9.7",
+        "typescript": "^5.8.3",
+        "vinxi": "^0.5.8",
+        "vitest": "^4.1.8"
+    },
+    "peerDependencies": {
+        "solid-js": "^1.9.7",
+        "vinxi": "^0.5.8"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../server.ts"],"names":[],"mappings":"AAkfA,QAAA,MAAM,OAAO,2FAqYX,CAAC;AAEH,eAAe,OAAO,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../server.ts"],"names":[],"mappings":"AA2iBA,QAAA,MAAM,OAAO,2FAmdX,CAAC;AAEH,eAAe,OAAO,CAAC"}