@nobody6146/polite-cli v1.1.0

Polite

Polite is a lightweight reactive JS framework for building SPAs on top of HTML custom elements without the need for a build step.

Here are some of the features Polite supports out of the box:

• Create dynamic websites at runtime from static files without the need for a build step (excluding the TypeScript compiler)
• Client-side rendering
• HTML templating and custom components
• Lazy loading components
• Reactive state through the use of signals
• Built ontop of custom HTML elements
• One-way and two-way model binding
• Client-side routing and routing middleware
• Depdency injection
• JS Modules and TypeScript support

What to know

Polite is a self contained front-end framework solution. Polite components bundle all the code needed to function inside of the HTML custom element's definition. There is no global JS context needed to manage these components or to communicate with other Polite components. This means if you bundle your Polite component (include the framework and all referenced code), you can reuse these components inside any webpage or framework!

CLI install instructions

1. Install the NPM package globally: npm install -g @nobody6146/polite-cli
2. Navigate to your project directory
3. You can type polite version to check version informaiton or type polite help to see a list of commands. Additionally, typing --help or -h on any command will display help information about that command.
4. Start using the CLI!

How to make a brand new Hydrate App project

Although you don't need a whole project template to use Polite, the built in scaffolder generates a project setup that allows you to rapidly build a client-side routing application by organizing code. 1. Install the CLI from the CLI inall instructions above 2. Type polite app 'My-App' to scaffold out a new project in a folder called "My-App", and then navigate to that folder (This command will create a polite-config.json file that the CLI will use to determine how future commands will need to function) 3. Once inside, using your prefereed method to host static files (such as VS Code's Live Server extension or a NodeJS server), serve this folder as the root directory so the application will be able to access all the files 4. index.html will be the application entry point 5. Use the commands polite component <name> and polite service <name> to create additional components and service dependencies for your application. The commands will automatically create the resources needed and automatically include them in necessary files to get the new piece of code connected and ready to use immedately.

Import Polite into an existing application

Polite is not a structured framework, but a library. This makes it easy to add to existing projects if you just need a little bit of interactivity, and makes importing the newest version of Hydrate easy. You can accomplish this with the following steps: 1. Install the CLI from the CLI inall instructions above 2. Use the polite lib command to copy the Polite framework source files into your project 3. That is it! Polite is now ready to use how you like! If you would like to use the CLI as well, continue reading the additional steps 4. The CLI needs a polite-config.json file to know how to execute it's commands. You can manually do this by using the command polite init. The configuration file will allow you to modify the default behavior of the CLI and signal to it where to look in your project for making changes when it needs to generate additional resources.

Prod Release

Polite works without compiling your source code, so the JS you write will be the same JS that runs. Because the framework utilizes the JS Modules design pattern, this can lead to splitting your code accross several files. When testing on your local machine, fetching multiple code files is a trivial perfromance task for the browser. However, in a deployed environment, making excessive HTTP request can become a performance issue. For this reason, we recommend bundling your code to reduce the number of files and their size that must be requested by the SPA to run. This could include things such as using minifiers, bundlers, packers, etc. to combine files and save on space. Common choices would be the tool Webpack, using the TypeScript compiler and a module loader, or something equivalent.

If you want a simple solution, we recommend the NPM package tool "Rollup". It is a simple tool that allows you to easily bundle your code into a single file without the need of modules or requiring a loader. For this reason, if you used polite app to create a Polite application, you will see a rollup.config.mjs which is a configuration file for rollup that will help you automatically get your project bundled. To automatically bundle your app, simply run the command rollup -c -w to run the rollup configuration and put it in watch mode (automatically bundle with code changes) into the file bundle.js. You can now go to your index.html file of your app and comment out the script tag loading your index.js file (the heart of the app) and instead uncomment the script tag that imports the bundle.js to run the new bundled version of our code.