create-flowdular 0.1.0 → 0.2.0

package/README.md

@@ -1,51 +1,91 @@
+[![Flowdular: Build your business platform](https://cdn.jsdelivr.net/npm/create-flowdular@latest/assets/flowdular-banner.png)](https://flowdular.com)
+
 # create-flowdular
 
-Scaffold a Flowdular application.
+[![npm version](https://img.shields.io/npm/v/create-flowdular?color=f59e0b)](https://www.npmjs.com/package/create-flowdular)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.22.2-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Flowdular/flowdular/blob/main/LICENSE)
+
+Create a Flowdular application with the platform, an example module and local development configuration. Start with embedded PostgreSQL, then extend the application with your own business modules.
+
+## Quick start
+
+Use Node.js **22.22.2 or newer**:
 
-```bash
+```sh
 npm create flowdular@latest my-app
+cd my-app
 ```
 
-`pnpm create flowdular my-app` and `yarn create flowdular my-app` resolve to the
-same package. `npx create-flowdular@latest my-app` runs it directly.
+For this new local application, initialize demo authentication and start the development server:
 
-It creates the directory, copies the template (the platform plus one example
-module), rewrites the package name, generates this app's secret keys into
-`.env`, installs the pnpm workspace dependencies, and
-makes the first commit.
+```sh
+pnpm flowdular setup quick --apply --confirm reset-local-auth
+pnpm dev
+```
 
-## Options
+Open [localhost:4310](http://localhost:4310). `setup quick` resets local authentication; use it only for a fresh local workspace with its default database.
+
+`npm create` launches the generator. The generated application uses **pnpm workspaces**. If pnpm is unavailable during installation, the generator invokes its pinned version through `npm exec`.
 
-| Option                  | Default   | Effect                                      |
-| ----------------------- | --------- | ------------------------------------------- |
-| `-t, --template <name>` | `default` | Template to copy                            |
-| `--pm <manager>`        | `pnpm`    | Use `pnpm` for this template                |
-| `--no-install`          | installs  | Skip dependency installation                |
-| `--no-git`              | commits   | Skip repository initialization              |
-| `-f, --force`           | refuses   | Scaffold into a directory that is not empty |
-| `-h, --help`            |           | Show usage                                  |
-| `-v, --version`         |           | Show the version                            |
+You can also launch the generator directly:
 
-## What it generates
+```sh
+npx create-flowdular@latest my-app
+```
+
+## What you get
 
-Local development runs on embedded PostgreSQL, so a new app needs no database
-server and no connection string. The generated `.env` sets
-`FD_DATABASE_ADAPTER=pglite` and one fresh base64 encoded 32 byte key per
-secret: `FD_AGENT_CREDENTIAL_KEY`, `FD_AGENT_RUN_GRANT_KEY`,
-`FD_WORKFLOWS_PAYLOAD_KEY`, `FD_WORKFLOWS_CURSOR_KEY` and `FD_AUTH_MFA_KEY`. The
-keys differ on every run and never leave the machine.
+| Included          | Purpose                                                    |
+| ----------------- | ---------------------------------------------------------- |
+| `platform/`       | Application shell and generated module composition         |
+| `modules/`        | An example module and space for your business modules      |
+| `flowdular.json`  | Workspace and module configuration                         |
+| `.env`            | Local database selection and freshly generated secret keys |
+| Workspace scripts | Development server, type checking, tests and validation    |
 
-The scaffolder makes no network call of its own; the only one is the package
-manager install, which `--no-install` skips. It collects nothing.
+The generator installs dependencies and initializes Git by default. Local development uses PGlite, an embedded PostgreSQL implementation, so the default setup needs no external database server.
 
-## After it finishes
+## Options
 
-```bash
+Pass generator flags after `--` when using `npm create`:
+
+```sh
+npm create flowdular@latest my-app -- --no-install --no-git
 cd my-app
-pnpm flowdular setup quick --apply --confirm reset-local-auth
-pnpm dev
+pnpm install
+```
+
+| Option                  | Behavior                                                      |
+| ----------------------- | ------------------------------------------------------------- |
+| `-t, --template <name>` | Select a template; defaults to `default`                      |
+| `--pm pnpm`             | Select the package manager supported by this template         |
+| `--no-install`          | Generate files without installing dependencies                |
+| `--no-git`              | Skip Git initialization and the initial commit                |
+| `-f, --force`           | Allow a nonempty target directory; inspect its contents first |
+| `-h, --help`            | Show usage                                                    |
+| `-v, --version`         | Show the generator version                                    |
+
+## Configuration and secrets
+
+Each run generates separate random 32-byte keys for agent credentials, agent grants, workflow payloads, workflow cursors and authentication MFA. They are written to the new application's `.env`. Keep that file private and provide deployment secrets through your hosting environment.
+
+The default adapter is `FD_DATABASE_ADAPTER=pglite`. For a hosted PostgreSQL deployment, follow the [database adapter guide](https://github.com/Flowdular/flowdular/blob/main/docs/database-adapters.md) and [configuration reference](https://github.com/Flowdular/flowdular/blob/main/docs/configuration.md).
+
+## Next steps
+
+```sh
+pnpm flowdular doctor
+pnpm verify
+pnpm flowdular help
 ```
 
-Then open <http://localhost:4310>.
+Read the [module guide](https://github.com/Flowdular/flowdular/blob/main/docs/modules.md) to extend the application. Business modules from [Official Modules](https://github.com/Flowdular/official-modules) are installed as source through the CLI.
+
+## Packages and support
+
+- [@flowdular/sdk](https://www.npmjs.com/package/@flowdular/sdk): shared platform APIs, UI and core modules.
+- [flowdular](https://www.npmjs.com/package/flowdular): workspace CLI.
+- [Documentation](https://github.com/Flowdular/flowdular/tree/main/docs) · [Source and issues](https://github.com/Flowdular/flowdular) · [Website](https://flowdular.com)
 
-`npm create` launches the generator; the generated application uses pnpm workspaces. If pnpm is missing, the generator runs the pinned pnpm version through `npm exec`. The only Flowdular dependencies published to npm are `@flowdular/sdk`, `flowdular` and `create-flowdular`. UI is available through `@flowdular/sdk/ui` and `@flowdular/sdk/ui/styles`.
+Licensed under MIT. Repository documentation and source require repository access while the repositories are private.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-flowdular",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"type": "module",
 	"description": "Scaffold a Flowdular application: the platform, one example module and the secrets a fresh install needs.",
 	"license": "MIT",
@@ -24,7 +24,8 @@
 	"files": [
 		"dist",
 		"template",
-		"README.md"
+		"README.md",
+		"assets"
 	],
 	"engines": {
 		"node": ">=22.22.2"

package/template/default/modules/example/package.json

@@ -16,12 +16,12 @@
 	"dependencies": {
 		"octane": "0.1.51",
 		"segment-state": "0.2.0",
-		"@flowdular/sdk": "0.1.0"
+		"@flowdular/sdk": "0.2.0"
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",
 		"@types/node": "24.13.3",
 		"typescript": "5.9.3",
-		"vitest": "4.1.10"
+		"vitest": "4.1.11"
 	}
 }

package/template/default/package.json

@@ -21,6 +21,6 @@
 	"devDependencies": {
 		"@tsrx/prettier-plugin": "0.3.120",
 		"prettier": "3.6.2",
-		"flowdular": "0.1.0"
+		"flowdular": "0.2.0"
 	}
 }

package/template/default/platform/octane.config.ts

@@ -1,6 +1,8 @@
 import {
 	assertRouteConflicts,
 	createModuleWebRoutes,
+	createApplicationRoutes,
+	validateApplicationPath,
 } from '@flowdular/sdk/server';
 import { resolve } from 'node:path';
 import { defineConfig, RenderRoute } from '@octanejs/vite-plugin';
@@ -16,6 +18,7 @@ import {
 import {
 	composeModuleServer,
 	moduleWebMounts,
+	applicationBasePath,
 } from './src/generated/modules.server.ts';
 import {
 	createPlatformDatabaseProvider,
@@ -35,8 +38,12 @@ const workspaceRoot = resolve(import.meta.dirname, '..');
 const databases = createPlatformDatabaseProvider(
 	databaseProviderConfigFromEnvironment(process.env, workspaceRoot),
 );
+const configuredApplicationPath = validateApplicationPath(
+	process.env.FD_APPLICATION_PATH ?? applicationBasePath,
+);
 const authRuntime = createAuthRuntime({
 	...authRuntimeOptionsFromEnvironment(process.env, workspaceRoot),
+	applicationPath: configuredApplicationPath,
 	databases,
 });
 
@@ -83,22 +90,17 @@ export default defineConfig({
 	middlewares: [authRuntime.middleware],
 	router: {
 		routes: checkedRoutes([
-			new RenderRoute({ path: '/', entry: SHELL }),
-			new RenderRoute({ path: '/auth', entry: SHELL }),
-			new RenderRoute({ path: '/auth/login', entry: SHELL }),
-			new RenderRoute({ path: '/auth/register', entry: SHELL }),
-			new RenderRoute({ path: '/auth/forgot-password', entry: SHELL }),
-			new RenderRoute({ path: '/auth/reset-password', entry: SHELL }),
-			new RenderRoute({ path: '/auth/accept-invitation', entry: SHELL }),
-			new RenderRoute({ path: '/auth/mfa', entry: SHELL }),
-			new RenderRoute({ path: '/app', entry: SHELL }),
-			new RenderRoute({ path: '/app/:workspace', entry: SHELL }),
-			new RenderRoute({ path: '/app/:workspace/:view', entry: SHELL }),
+			...createApplicationRoutes({
+				path: configuredApplicationPath,
+				entry: SHELL,
+				publicRoot: moduleWebMounts.some((site) => site.path === '/'),
+			}),
 			...createAuthRoutes(authRuntime),
 			...moduleCompositions.flatMap((composition) => composition.routes),
 			...createModuleWebRoutes({
 				modules: moduleCompositions,
 				mounts: moduleWebMounts,
+				applicationPath: configuredApplicationPath,
 				resolveIdentity: (context) => {
 					const principal = principalFromContext(context);
 					return principal
@@ -110,8 +112,6 @@ export default defineConfig({
 						: null;
 				},
 			}),
-			new RenderRoute({ path: '/:workspace', entry: SHELL }),
-			new RenderRoute({ path: '/:workspace/:view', entry: SHELL }),
 		]),
 	},
 });

package/template/default/platform/package.json

@@ -14,7 +14,7 @@
 		"@octanejs/vite-plugin": "0.1.51",
 		"octane": "0.1.51",
 		"pg": "8.23.0",
-		"@flowdular/sdk": "0.1.0"
+		"@flowdular/sdk": "0.2.0"
 	},
 	"devDependencies": {
 		"@octanejs/app-core": "0.0.47",

package/template/default/platform/src/App.tsrx

@@ -1,4 +1,4 @@
-import { configureApplicationRouting } from '@flowdular/sdk/client/routing';
+import { configureApplicationFromPage } from '@flowdular/sdk/client/routing';
 import {
 	ApplicationShell,
 	activeLocale,
@@ -12,11 +12,12 @@ import {
 import type { AuthPrincipal } from '@flowdular/sdk/modules/auth';
 import { Head } from '@octanejs/seo';
 import type { RenderRouteProps } from '@octanejs/vite-plugin';
-import { createModuleClientContributions, applicationBasePath } from './generated/modules.client.ts';
+import {
+	createModuleClientContributions,
+	applicationBasePath,
+} from './generated/modules.client.ts';
 import './styles.css';
 
-configureApplicationRouting(applicationBasePath);
-
 interface AuthenticatedAppProps {
 	initialUrl: string;
 	principal: AuthPrincipal;
@@ -62,6 +63,7 @@ function AuthenticatedApp(props: AuthenticatedAppProps) @{
 }
 
 export function App(props?: RenderRouteProps) @{
+	configureApplicationFromPage(props, applicationBasePath);
 	const initialUrl =
 		props?.url ?? (typeof window === 'undefined' ? '/' : window.location.href);
 	<Head>

package/template/default/platform/src/generated/modules.client.ts

@@ -1,5 +1,6 @@
 /* GENERATED by "flowdular module sync". Do not edit by hand; run
    "pnpm flowdular module sync --apply" after enabling or disabling modules. */
+export const applicationBasePath = '/app';
 import type {
 	ModuleClientContext,
 	ModuleClientContribution,

package/template/default/platform/src/generated/modules.server.ts

@@ -4,6 +4,7 @@ import type {
 	PlatformServerComposition,
 	PlatformServerContext,
 } from '@flowdular/sdk/modules/auth/server';
+import type { WebMount } from '@flowdular/sdk/server';
 import { createServerComposition as system_core } from '@flowdular/sdk/modules/system/platform';
 import { createServerComposition as example_core } from '@app/module-example/platform';
 
@@ -28,4 +29,5 @@ export function composeModuleServer(
 	];
 }
 
-export const moduleWebMounts = [] as const;
+export const moduleWebMounts: readonly WebMount[] = [] as const;
+export const applicationBasePath = '/app';