readme

Author: pyramation

README.md

@@ -13,36 +13,46 @@
   </a>
 </p>
 
-KubernetesJS is a **fully-typed**, zero-dependency TypeScript client for Kubernetes.
+KubernetesJS is a comprehensive TypeScript ecosystem for Kubernetes, providing **fully-typed**, zero-dependency clients and React hooks for building modern cloud-native applications.
 
 Write infrastructure like you write apps—modular, composable, and testable. KubernetesJS gives you direct, programmatic access to the entire Kubernetes API, with the developer experience of modern JavaScript tooling.
 
 > No more brittle YAML. No more hidden chart logic. Just pure, type-safe Kubernetes from the language you already use.
 
+## Packages
 
-## Features
+### 📦 [`kubernetesjs`](./packages/kubernetesjs) - Core TypeScript Client
+The foundation package providing a fully-typed, zero-dependency TypeScript client for the entire Kubernetes API. Perfect for Node.js applications, CLI tools, operators, and automation scripts.
 
-- **🔒 Fully Typed**: Complete TypeScript definitions for all functions and models for an enhanced development experience.
-- **🚀 Zero Dependencies**: Works out of the box without the need for additional installations.
-- **📡 Full Kubernetes API Coverage**: Supports all Kubernetes API endpoints with detailed TypeScript types.
-- **🌐 Cross-Platform**: Works with both Node.js and browser environments.
-
-With KubernetesJS, you don’t shell out to `kubectl`, grep logs, or decode YAML trees. You write real code—typed, composable, inspectable.
+```bash
+npm install kubernetesjs
+```
 
-## Installation
+[View kubernetesjs documentation →](./packages/kubernetesjs)
 
-To install KubernetesJS, you can use npm or yarn:
+### ⚛️ [`@kubernetesjs/react`](./packages/react) - React Hooks for Kubernetes
+React hooks powered by TanStack Query for building reactive Kubernetes dashboards and management UIs. Includes intelligent caching, real-time updates, and optimistic mutations.
 
 ```bash
-npm install kubernetesjs
-# or
-yarn add kubernetesjs
-
+npm install @kubernetesjs/react
 ```
 
-## Your Infrastructure, Like a Component
+[View @kubernetesjs/react documentation →](./packages/react)
 
-This is what we mean by "*React for infrastructure*":
+## Features
+
+- **🔒 Fully Typed**: Complete TypeScript definitions for all functions and models for an enhanced development experience.
+- **🚀 Zero Dependencies**: Core client works out of the box without additional installations.
+- **📡 Full Kubernetes API Coverage**: Supports all Kubernetes API endpoints with detailed TypeScript types.
+- **🌐 Cross-Platform**: Works with both Node.js and browser environments.
+- **⚛️ React Integration**: First-class React hooks with intelligent state management.
+- **🔄 Real-time Updates**: Built-in support for watching resources and automatic refetching.
+
+With KubernetesJS, you don't shell out to `kubectl`, grep logs, or decode YAML trees. You write real code—typed, composable, inspectable.
+
+## Quick Start
+
+### Core Client Usage
 
 ```ts
 import { KubernetesClient } from "kubernetesjs";
@@ -51,6 +61,7 @@ const client = new KubernetesClient({
   restEndpoint: process.env.KUBERNETES_API_URL || 'http://127.0.0.1:8001'
 });
 
+// Create a deployment
 await client.createAppsV1NamespacedDeployment({
   path: { namespace: 'default' },
   body: {
@@ -63,55 +74,57 @@ await client.createAppsV1NamespacedDeployment({
       template: {
         metadata: { labels: { app: 'hello-world' } },
         spec: {
-          containers: [
-            {
-              name: 'app',
-              image: 'node:18-alpine',
-              command: ['node', '-e', 'require("http").createServer((_,res)=>res.end("ok")).listen(3000)'],
-              ports: [{ containerPort: 3000 }]
-            }
-          ]
+          containers: [{
+            name: 'app',
+            image: 'node:18-alpine',
+            command: ['node', '-e', 'require("http").createServer((_,res)=>res.end("ok")).listen(3000)'],
+            ports: [{ containerPort: 3000 }]
+          }]
         }
       }
     }
   }
 });
 ```
 
-## Test Your Cluster Like You Test Code
-
-Run infrastructure as part of your test suite, with assertions.
-
-```ts
-describe('PostgreSQL Deployment', () => {
-  const namespace = 'default';
-  const deploymentName = 'postgres-pgvector';
-
-  it('creates a PostgreSQL deployment + service', async () => {
-    const deployment = await client.createAppsV1NamespacedDeployment({ ... });
-    const service = await client.createCoreV1NamespacedService({ ... });
+### React Hooks Usage
 
-    expect(deployment.metadata?.name).toBe(deploymentName);
-    expect(service.metadata?.name).toBe(deploymentName);
+```tsx
+import { KubernetesProvider, useListCoreV1NamespacedPodQuery } from '@kubernetesjs/react';
 
-    const status = await client.readAppsV1NamespacedDeployment({
-      path: { namespace, name: deploymentName }
-    });
+function App() {
+  return (
+    <KubernetesProvider initialConfig={{ restEndpoint: 'http://127.0.0.1:8001' }}>
+      <PodList namespace="default" />
+    </KubernetesProvider>
+  );
+}
 
-    expect(status.status?.readyReplicas).toBe(1);
+function PodList({ namespace }: { namespace: string }) {
+  const { data, isLoading } = useListCoreV1NamespacedPodQuery({
+    path: { namespace }
   });
-});
-```
 
-> Type-safe Kubernetes. With `expect()`.
-
----
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <ul>
+      {data?.items?.map(pod => (
+        <li key={pod.metadata?.uid}>
+          {pod.metadata?.name} - {pod.status?.phase}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
 
-## Declarative Loops, Composability, Reuse
+## Your Infrastructure, Like a Component
 
-You can now treat infrastructure like reusable components or functions:
+This is what we mean by "*React for infrastructure*":
 
 ```ts
+// Reusable infrastructure components
 function createPostgresDeployment(name: string) {
   return client.createAppsV1NamespacedDeployment({
     path: { namespace: 'default' },
@@ -123,8 +136,27 @@ function createPostgresDeployment(name: string) {
     }
   });
 }
+
+// Test your infrastructure
+describe('PostgreSQL Deployment', () => {
+  it('creates a PostgreSQL deployment + service', async () => {
+    const deployment = await createPostgresDeployment('postgres-test');
+    const service = await createPostgresService('postgres-test');
+
+    expect(deployment.metadata?.name).toBe('postgres-test');
+    expect(service.metadata?.name).toBe('postgres-test');
+
+    const status = await client.readAppsV1NamespacedDeployment({
+      path: { namespace: 'default', name: 'postgres-test' }
+    });
+
+    expect(status.status?.readyReplicas).toBe(1);
+  });
+});
 ```
 
+> Type-safe Kubernetes. With `expect()`.
+
 ## Example: Inspect Init Containers in Running Pods
 
 ```ts
@@ -188,6 +220,6 @@ Checkout these related projects:
 
 ## Disclaimer
 
-AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED “AS IS”, AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
 
-No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.