@adonisjs/inertia 1.0.0-0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License
+
+Copyright (c) 2023
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @adonisjs/inertia
+
+<br />
+
+[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url]
+
+## Introduction
+Official [Inertia.js](https://inertiajs.com/) adapter for AdonisJS.
+
+## Official Documentation
+The documentation is available on the [AdonisJS website](https://docs.adonisjs.com/guides/inertia/introduction).
+
+## Contributing
+One of the primary goals of AdonisJS is to have a vibrant community of users and contributors who believes in the principles of the framework.
+
+We encourage you to read the [contribution guide](https://github.com/adonisjs/.github/blob/main/docs/CONTRIBUTING.md) before contributing to the framework.
+
+## Code of Conduct
+In order to ensure that the AdonisJS community is welcoming to all, please review and abide by the [Code of Conduct](https://github.com/adonisjs/.github/blob/main/docs/CODE_OF_CONDUCT.md).
+
+## License
+AdonisJS Lucid is open-sourced software licensed under the [MIT license](LICENSE.md).
+
+[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/inertia/test.yml?style=for-the-badge
+[gh-workflow-url]: https://github.com/adonisjs/inertia/actions/workflows/test.yml "Github action"
+
+[npm-image]: https://img.shields.io/npm/v/@adonisjs/inertia/latest.svg?style=for-the-badge&logo=npm
+[npm-url]: https://www.npmjs.com/package/@adonisjs/inertia/v/latest "npm"
+
+[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+
+[license-url]: LICENSE.md
+[license-image]: https://img.shields.io/github/license/adonisjs/inertia?style=for-the-badge

package/build/configure.js

@@ -0,0 +1,82 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+const ADAPTERS = ['Vue 3', 'React', 'Svelte'];
+const ADAPTERS_INFO = {
+    'Vue 3': {
+        dependencies: [
+            { name: '@inertiajs/vue3', isDevDependency: false },
+            { name: 'vue', isDevDependency: false },
+            { name: '@vitejs/plugin-vue', isDevDependency: true },
+        ],
+    },
+    'React': {
+        dependencies: [
+            { name: '@inertiajs/inertia-react', isDevDependency: false },
+            { name: 'react', isDevDependency: false },
+            { name: 'react-dom', isDevDependency: false },
+            { name: '@vitejs/plugin-react', isDevDependency: true },
+            { name: '@types/react', isDevDependency: true },
+            { name: '@types/react-dom', isDevDependency: true },
+        ],
+    },
+    'Svelte': {
+        dependencies: [
+            { name: '@inertiajs/inertia-svelte', isDevDependency: false },
+            { name: 'svelte', isDevDependency: false },
+            { name: '@sveltejs/vite-plugin-svelte', isDevDependency: true },
+        ],
+    },
+};
+/**
+ * Configures the package
+ */
+export async function configure(command) {
+    /**
+     * Prompt for adapter
+     */
+    const adapter = await command.prompt.choice('Select the Inertia adapter you want to use', ADAPTERS, { name: 'adapter' });
+    const pkgToInstall = ADAPTERS_INFO[adapter].dependencies;
+    /**
+     * Prompt for SSR
+     */
+    const withSsr = await command.prompt.confirm('Do you want to enable server-side rendering?', {
+        name: 'ssr',
+    });
+    if (withSsr) {
+        pkgToInstall.push(...(ADAPTERS_INFO[adapter].ssrDependencies || []));
+    }
+    const codemods = await command.createCodemods();
+    /**
+     * Publish provider
+     */
+    await codemods.updateRcFile((rcFile) => {
+        rcFile.addProvider('@adonisjs/inertia/inertia_provider');
+    });
+    /**
+     * Add Inertia middleware
+     */
+    codemods.registerMiddleware('router', [
+        { path: '@adonisjs/inertia/inertia_middleware', position: 'after' },
+    ]);
+    /**
+     * Publish config
+     */
+    await command.publishStub('config.stub');
+    /**
+     * Install packages
+     */
+    const shouldInstallPackages = await command.prompt.confirm(`Do you want to install dependencies ${pkgToInstall.map((pkg) => pkg.name).join(', ')}?`, { name: 'install' });
+    if (shouldInstallPackages) {
+        command.installPackages(pkgToInstall);
+    }
+    else {
+        command.listPackagesToInstall(pkgToInstall);
+    }
+    command.logger.success('Inertia was configured successfully. Please note that you still need to update your vite config, setup your Edge root view and others things. Read the docs for more info.');
+}

package/build/index.d.ts

@@ -0,0 +1,3 @@
+export { configure } from './configure.js';
+export { stubsRoot } from './stubs/main.js';
+export { defineConfig } from './src/define_config.js';

package/build/index.js

@@ -0,0 +1,11 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+export { configure } from './configure.js';
+export { stubsRoot } from './stubs/main.js';
+export { defineConfig } from './src/define_config.js';

package/build/providers/inertia_provider.d.ts

@@ -0,0 +1,26 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+import { Inertia } from '../src/inertia.js';
+/**
+ * HttpContext augmentations
+ */
+declare module '@adonisjs/core/http' {
+    interface HttpContext {
+        inertia: Inertia;
+    }
+}
+/**
+ * Inertia provider
+ */
+export default class InertiaProvider {
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    /**
+     * Registers edge plugin when edge is installed
+     */
+    protected registerEdgePlugin(): Promise<void>;
+    /**
+     * Register Inertia middleware, edge plugin, and add
+     * `inertia` property to the HttpContext
+     */
+    boot(): Promise<void>;
+}

package/build/providers/inertia_provider.js

@@ -0,0 +1,46 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { HttpContext } from '@adonisjs/core/http';
+import { Inertia } from '../src/inertia.js';
+import { VersionCache } from '../src/version_cache.js';
+import InertiaMiddleware from '../src/inertia_middleware.js';
+/**
+ * Inertia provider
+ */
+export default class InertiaProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    /**
+     * Registers edge plugin when edge is installed
+     */
+    async registerEdgePlugin() {
+        try {
+            const edgeExports = await import('edge.js');
+            const { edgePluginInertia } = await import('../src/plugins/edge.js');
+            edgeExports.default.use(edgePluginInertia());
+        }
+        catch { }
+    }
+    /**
+     * Register Inertia middleware, edge plugin, and add
+     * `inertia` property to the HttpContext
+     */
+    async boot() {
+        const appRoot = this.app.appRoot;
+        const config = this.app.config.get('inertia', { view: 'app' });
+        const versionCache = await new VersionCache(appRoot, config.assetsVersion).computeVersion();
+        this.app.container.singleton(InertiaMiddleware, () => new InertiaMiddleware(versionCache));
+        HttpContext.getter('inertia', function inertia() {
+            return new Inertia(this, config, versionCache.getVersion());
+        }, false);
+        await this.registerEdgePlugin();
+    }
+}

package/build/src/debug.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="node" resolution-mode="require"/>
+declare const _default: import("util").DebugLogger;
+export default _default;

package/build/src/debug.js

@@ -0,0 +1,10 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { debuglog } from 'node:util';
+export default debuglog('adonisjs:inertia');

package/build/src/define_config.d.ts

@@ -0,0 +1,5 @@
+import type { InertiaConfig } from './types.js';
+/**
+ * Define the Inertia configuration
+ */
+export declare function defineConfig(config: InertiaConfig): InertiaConfig;

package/build/src/define_config.js

@@ -0,0 +1,14 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * Define the Inertia configuration
+ */
+export function defineConfig(config) {
+    return config;
+}

package/build/src/inertia.d.ts

@@ -0,0 +1,39 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { InertiaConfig, MaybePromise, PageProps, AssetsVersion } from './types.js';
+/**
+ * Main class used to interact with Inertia
+ */
+export declare class Inertia {
+    #private;
+    protected ctx: HttpContext;
+    protected config: InertiaConfig;
+    protected version: AssetsVersion;
+    constructor(ctx: HttpContext, config: InertiaConfig, version: AssetsVersion);
+    /**
+     * Render a page using Inertia
+     */
+    render(component: string, pageProps?: PageProps): Promise<string | {
+        component: string;
+        version: AssetsVersion;
+        props: any;
+        url: string;
+    }>;
+    /**
+     * Create a lazy prop
+     *
+     * Lazy props are never resolved on first visit, but only when the client
+     * request a partial reload explicitely with this value.
+     *
+     * See https://inertiajs.com/partial-reloads#lazy-data-evaluation
+     */
+    lazy(callback: () => MaybePromise<any>): {
+        [x: symbol]: () => MaybePromise<any>;
+    };
+    /**
+     * This method can be used to redirect the user to an external website
+     * or even a non-inertia route of your application.
+     *
+     * See https://inertiajs.com/redirects#external-redirects
+     */
+    location(url: string): Promise<void>;
+}

package/build/src/inertia.js

@@ -0,0 +1,119 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * Main class used to interact with Inertia
+ */
+export class Inertia {
+    ctx;
+    config;
+    version;
+    /**
+     * The name of the Edge view that will be used to render the page.
+     */
+    #edgeRootView;
+    /**
+     * Symbol used to identify lazy props
+     */
+    #kLazySymbol = Symbol('lazy');
+    constructor(ctx, config = {}, version) {
+        this.ctx = ctx;
+        this.config = config;
+        this.version = version;
+        this.#edgeRootView = config.rootView || 'root';
+    }
+    /**
+     * Check if a value is a lazy prop
+     */
+    #isLazyProps(value) {
+        return typeof value === 'object' && value && this.#kLazySymbol in value;
+    }
+    /**
+     * Pick props to resolve based on x-inertia-partial-data header
+     *
+     * If header is not present, resolve all props except lazy props
+     * If header is present, resolve only the props that are listed in the header
+     */
+    #pickPropsToResolve(component, props) {
+        const partialData = this.ctx.request
+            .header('x-inertia-partial-data')
+            ?.split(',')
+            .filter(Boolean);
+        const partialComponent = this.ctx.request.header('x-inertia-partial-component');
+        let entriesToResolve = Object.entries(props);
+        if (partialData && partialComponent === component) {
+            entriesToResolve = entriesToResolve.filter(([key]) => partialData.includes(key));
+        }
+        else {
+            entriesToResolve = entriesToResolve.filter(([key]) => !this.#isLazyProps(props[key]));
+        }
+        return entriesToResolve;
+    }
+    /**
+     * Resolve the props that will be sent to the client
+     */
+    async #resolvePageProps(component, props) {
+        const entriesToResolve = this.#pickPropsToResolve(component, props);
+        const entries = entriesToResolve.map(async ([key, value]) => {
+            if (typeof value === 'function') {
+                return [key, await value(this.ctx)];
+            }
+            if (this.#isLazyProps(value)) {
+                const lazyValue = value[this.#kLazySymbol];
+                return [key, await lazyValue()];
+            }
+            return [key, value];
+        });
+        return Object.fromEntries(await Promise.all(entries));
+    }
+    /**
+     * Build the page object that will be returned to the client
+     *
+     * See https://inertiajs.com/the-protocol#the-page-object
+     */
+    async #buildPageObject(component, pageProps) {
+        return {
+            component,
+            version: this.version,
+            props: await this.#resolvePageProps(component, { ...this.config.sharedData, ...pageProps }),
+            url: this.ctx.request.url(true),
+        };
+    }
+    /**
+     * Render a page using Inertia
+     */
+    async render(component, pageProps) {
+        const pageObject = await this.#buildPageObject(component, pageProps);
+        const isInertiaRequest = !!this.ctx.request.header('x-inertia');
+        if (!isInertiaRequest) {
+            return this.ctx.view.render(this.#edgeRootView, { page: pageObject });
+        }
+        return pageObject;
+    }
+    /**
+     * Create a lazy prop
+     *
+     * Lazy props are never resolved on first visit, but only when the client
+     * request a partial reload explicitely with this value.
+     *
+     * See https://inertiajs.com/partial-reloads#lazy-data-evaluation
+     */
+    lazy(callback) {
+        return { [this.#kLazySymbol]: callback };
+    }
+    /**
+     * This method can be used to redirect the user to an external website
+     * or even a non-inertia route of your application.
+     *
+     * See https://inertiajs.com/redirects#external-redirects
+     */
+    async location(url) {
+        this.ctx.response.header('X-Inertia-Location', url);
+        this.ctx.response.status(409);
+    }
+}

package/build/src/inertia_middleware.d.ts

@@ -0,0 +1,12 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { NextFn } from '@adonisjs/core/types/http';
+import type { VersionCache } from './version_cache.js';
+/**
+ * Inertia middleware to handle the Inertia requests and
+ * set appropriate headers/status
+ */
+export default class InertiaMiddleware {
+    protected version: VersionCache;
+    constructor(version: VersionCache);
+    handle({ request, response }: HttpContext, next: NextFn): Promise<void>;
+}

package/build/src/inertia_middleware.js

@@ -0,0 +1,47 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * Inertia middleware to handle the Inertia requests and
+ * set appropriate headers/status
+ */
+export default class InertiaMiddleware {
+    version;
+    constructor(version) {
+        this.version = version;
+    }
+    async handle({ request, response }, next) {
+        await next();
+        const isInertiaRequest = !!request.header('x-inertia');
+        if (!isInertiaRequest)
+            return;
+        response.header('Vary', 'Accept');
+        response.header('X-Inertia', 'true');
+        /**
+         * When redirecting a PUT/PATCH/DELETE request, we need to change the
+         * we must use a 303 status code instead of a 302 to force
+         * the browser to use a GET request after redirecting.
+         *
+         * See https://inertiajs.com/redirects
+         */
+        const method = request.method();
+        if (response.getStatus() === 302 && ['PUT', 'PATCH', 'DELETE'].includes(method)) {
+            response.status(303);
+        }
+        /**
+         * Handle version change
+         *
+         * See https://inertiajs.com/the-protocol#asset-versioning
+         */
+        const version = this.version.getVersion();
+        if (method === 'GET' && request.header('x-inertia-version', '') !== version) {
+            response.header('x-inertia-location', request.url());
+            response.status(409);
+        }
+    }
+}

package/build/src/plugins/api_client.d.ts

@@ -0,0 +1,37 @@
+import type { PluginFn } from '@japa/runner/types';
+import type { PageProps } from '../types.js';
+declare module '@japa/api-client' {
+    interface ApiRequest {
+        /**
+         * Set `X-Inertia` header on the request
+         */
+        withInertia(): this;
+        /**
+         * Set `X-Inertia-Partial-Data` and `X-Inertia-Partial-Component` headers on the request
+         */
+        withInertiaPartialReload(component: string, data: string[]): this;
+    }
+    interface ApiResponse {
+        /**
+         * The inertia component
+         */
+        inertiaComponent?: string;
+        /**
+         * The inertia response props
+         */
+        inertiaProps: PageProps;
+        /**
+         * Assert component name of inertia response
+         */
+        assertInertiaComponent(component: string): this;
+        /**
+         * Assert props to be exactly the same as the given props
+         */
+        assertInertiaProps(props: PageProps): this;
+        /**
+         * Assert inertia props contains a subset of the given props
+         */
+        assertInertiaPropsContains(props: PageProps): this;
+    }
+}
+export declare function inertiaApiClient(): PluginFn;

package/build/src/plugins/api_client.js

@@ -0,0 +1,62 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { ApiRequest, ApiResponse } from '@japa/api-client';
+/**
+ * Ensure the response is an inertia response, otherwise throw an error
+ */
+function ensureIsInertiaResponse() {
+    if (!this.header('x-inertia')) {
+        throw new Error('Response is not an Inertia response. Make sure to call `withInertia()` on the request');
+    }
+}
+export function inertiaApiClient() {
+    return () => {
+        ApiRequest.macro('withInertia', function () {
+            this.header('x-inertia', 'true');
+            return this;
+        });
+        ApiRequest.macro('withInertiaPartialReload', function (component, data) {
+            this.withInertia();
+            this.header('X-Inertia-Partial-Data', data.join(','));
+            this.header('X-Inertia-Partial-Component', component);
+            return this;
+        });
+        /**
+         * Response getters
+         */
+        ApiResponse.getter('inertiaComponent', function () {
+            ensureIsInertiaResponse.call(this);
+            return this.body().component;
+        });
+        ApiResponse.getter('inertiaProps', function () {
+            ensureIsInertiaResponse.call(this);
+            return this.body().props;
+        });
+        /**
+         * Response assertions
+         */
+        ApiResponse.macro('assertInertiaComponent', function (component) {
+            ensureIsInertiaResponse.call(this);
+            this.assert.deepEqual(this.body().component, component);
+            return this;
+        });
+        ApiResponse.macro('assertInertiaProps', function (props) {
+            this.ensureHasAssert();
+            ensureIsInertiaResponse.call(this);
+            this.assert.deepEqual(this.body().props, props);
+            return this;
+        });
+        ApiResponse.macro('assertInertiaPropsContains', function (props) {
+            this.ensureHasAssert();
+            ensureIsInertiaResponse.call(this);
+            this.assert.containsSubset(this.body().props, props);
+            return this;
+        });
+    };
+}

package/build/src/plugins/edge.d.ts

@@ -0,0 +1,5 @@
+import type { PluginFn } from 'edge.js/types';
+/**
+ * Register the Inertia tags and globals within Edge
+ */
+export declare const edgePluginInertia: () => PluginFn<undefined>;

package/build/src/plugins/edge.js

@@ -0,0 +1,43 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { encode } from 'html-entities';
+import debug from '../debug.js';
+/**
+ * Register the Inertia tags and globals within Edge
+ */
+export const edgePluginInertia = () => {
+    return (edge) => {
+        debug('sharing globals and inertia tags with edge');
+        edge.global('inertia', (page = {}) => {
+            if (page.ssrBody)
+                return page.ssrBody;
+            return `<div id="app" data-page="${encode(JSON.stringify(page))}"></div>`;
+        });
+        edge.global('inertiaHead', (page) => {
+            const { ssrHead = [] } = page || {};
+            return ssrHead.join('\n');
+        });
+        edge.registerTag({
+            block: false,
+            tagName: 'inertia',
+            seekable: false,
+            compile(_, buffer, { filename, loc }) {
+                buffer.writeExpression(`out += state.inertia(state.page)`, filename, loc.start.line);
+            },
+        });
+        edge.registerTag({
+            block: false,
+            tagName: 'inertiaHead',
+            seekable: false,
+            compile(_, buffer, { filename, loc }) {
+                buffer.writeExpression(`out += state.inertiaHead(state.page)`, filename, loc.start.line);
+            },
+        });
+    };
+};

package/build/src/types.d.ts

@@ -0,0 +1,32 @@
+import type { HttpContext } from '@adonisjs/core/http';
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Props that will be passed to inertia render method
+ */
+export type PageProps = Record<string, unknown>;
+/**
+ * Shared data types
+ */
+export type Data = string | number | object | boolean;
+export type SharedDatumFactory = (ctx: HttpContext) => MaybePromise<Data>;
+export type SharedData = Record<string, Data | SharedDatumFactory>;
+/**
+ * Allowed values for the assets version
+ */
+export type AssetsVersion = string | number | undefined;
+export interface InertiaConfig {
+    /**
+     * Path to the Edge view that will be used as the root view for Inertia responses.
+     * @default root (resources/views/root.edge)
+     */
+    rootView?: string;
+    /**
+     * The version of your assets. Every client request will be checked against this version.
+     * If the version is not the same, the client will do a full reload.
+     */
+    assetsVersion?: AssetsVersion;
+    /**
+     * Data that should be shared with all rendered pages
+     */
+    sharedData?: SharedData;
+}

package/build/src/types.js

@@ -0,0 +1,9 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+export {};