Installation and Usage

Manual Installation

JSXPine is not a UI library. As mentionned in introduction, we provide a set of JSX components boosted with Alpine.js.

Those components can be copied simply by following these steps below:

1. Going to the corresponding page you want ;
2. In installation part, click on Manual in the tab view, the source code will be showed ;
3. Click on Copy button et voilà !

Configuration

You have to know what JSXPine is composed.

Like Shadcn, the main entry point with your application is a file named: component.json.

This file contains information about propreties which define how components from JSXPine will be connected to your project.

These propreties are:

1. $schema: It's an url of the schema propreties of your component.json.

2. tailwind: Because JSXPine uses tailwind for the css part, this proprety handles two subpropreties.

   • config.js: This one is about your tailwind config file, ie where it's located.

   • css: This proprety's value is your global css file's path. It will applied everything set in this file to your components' style.

3. aliases: This proprety handles 3 crucial subpropreties, which are highly coupled between them:

   • common: This one is the path of all common type definitions.

   • components: This is the path of the folder where all components will be moved when added via cli (see here for more details). This value is also to be set in your tsconfig's path array.

   • scripts: Since JSXPine tries to use javascript in a better way, it suggests a folder called scripts when you can put all your logic, utilities or whatever you want as js code for your project. By default, it contains a subfolder named alpine. Therefore, this key is the path to this folder.

   • alpine: It's the path of the folder where everything related to alpinejs will be put. JSXPine uses advanced features of alpinejs, so this folder is intended to work with three of them.

     • -

       Data: A folder containing every functions register as data in alpinejs. See this link to learn more.

     • -

       Directive: Will contain custom directives in alpinejs. Check this link about directives.

     • -

       Magic: Will contain custom magic functions. Check this link about magic.

4. tsConfigAliases: This property holds either a property named "global" which is the alias in tsconfig of the directory containing common, components and scripts or three properties: common, components and scripts. Each key is an alias for the corresponding directory.

Dependencies

Some dependencies has been picked to best suit with JSXPine and its concept.

This section's goal is to make you understand why these ones have been selected.

• @kitajs/html: This package allows you tu write JSX in your application. Once installed, any Node/Deno/Bun can interpret your function component as html template. It provides a scan feature that tells you if your template is safe from XSS attacks.

• tailwindcss: Because JSXPine is based on tailwindcss classes, this one has to be part of your project.

• alpine.js: As same as tailwindcss, this one has to be part of your project in order to use all alpinejs features.

CLI

Like Shadcn, JSXPine has a CLI which will help you installing required modules and adding component(s).

With your chosen npm package manager, do:

npm install jsxpine

or

yarn add jsxpine

or

pnpm add jsxpine

or

bun add jsxpine

In case you don't want to install it locally, you can do:

npx jsxpine init

or

bunx jsxpine init

Init Command

The init command aims to prepare all required modules (mostly files) for you to use jsxpine components.

There are three optional arguments you can pass to this command:

• -c or --cwd < cwd >: This argument is the project's absolute path where everything will be installed. When empty, the current directory where the command is running is considered ;

• -y or --yes: Will skip confirmation prompt ;

• -h or --help: This command will print you in your terminal all commands.

When running this command (without --yes argument), several steps will be prompt to you:

1. Global CSS file: It's basically the main css file where all tailwind main function and also your global classes are defined. Please note that it will replace everything in this file by the boilerplate coming from jsxpine.

2. Tailwind config file: The init command will look up to the tailwind config file. If this file is not found, it exits from the the initialization process. Otherwise, it overwrites everything contain in this file.

3. Common' path: Everything like type definitions shared accross your components and js scripts are gathered in the common directory. Notes that to properly work, it has to be in the same directory than components and scripts.

4. Components' path: Because JSXPine is about "components", you'll have to define where to store them. This step lets you write the relative path of the directory which will contain all components added.

5. Scripts' path: As said before, JSXPine uses alpinejs. A scripts directory is created to hold all alpinejs features, but also everything related to js/ts which can be used by either your alpinejs functions, either by your jsx components.

   By doing this, the goal is to have a single file app.js/ts which will be used as source for your script tag.

   JSXPine promote the old web way, We hope you understand what we mean by that ;)

6. Set path alias in tsconfig.json: In this step, jsxpine first asks you if you want to automatically set some alias in your tsconfig.json. If you accept, it will then prompted to set a global alias or different alias name for common, components and scripts.

   If you choose a global alias, it will be something like $ui/common, $ui/components and $ui/scripts ($ui being the name chosen).

   In the case you choose individual name, you'll have $common, $components and $scripts (these values being what you typed in the prompt).

7. After installing dependencies, some properties related to @kitajs/html are added to your tsconfig.json (check this file and notice what has been added).

   Two more files are added: global.d.ts and alpine.d.ts. Each file corresponding to global type related to interface Window and alpinejs types.

Add Command

JSXPine provides a command called add that allows you to add a component to your project.

Here is how to use it: jsxpine add component-name.

The argument component-name is optional. By doing this, you have to choose your component(s) among the chekbox list displaying in the terminal.

When component-name is passed, it must match with the existing component name provide by JSXPine. Check the components' page or run jsxpine add to see the exhaustive list.

Where to Use It ?

JSXPine can be used in any js project that requires a UI library. This includes Node.js, Deno and Bun.

Because it's a reusable components library, it can be used in any framework that supports JSX. We will not too much detail things here, but these are some of them:

• Hono

• Elysia

• Express

• Fastify

• Nest

Actually, none of these is required to use JSXPine. You simply need @kitajs/html and a function that renders html.

For instance, in Hono, you can use ctx.html() function like this:

const ExampleView = () => {
	return (
		<div>
			<h1>Example</h1>
			<p>This is an example</p>
		</div>
	)
}

const router = new Hono().get("/example", (ctx) => {
	// This will render the ExampleView component when accessing "/example" endpoint
	return ctx.html(<ExampleView />);
})