Supe Project Creator v1.8.6

A simple tool for creating simple web projects with batteries included.

This is the first package under the @supeprojects scope, with more planned for the future.

Tip

Wait until v2.0.0 drops!

Overview - What is Supe Project Creator?

Supe Project Creator is a simple tool designed to help you build simple web applications quickly and efficiently. It generates project templates boilerplate using TypeScript, HTML, and CSS, with included hot reloading for a seamless development workflow. But there's a catch - the generated project has no dependencies, a fresh start. All the source code that runs the project will be waiting for you in the generated project folder, no strings attached. It's as simple as you can get.

The tool comes with a built-in web server, making it easy to test and deploy your projects locally or in production. One of the standout features is an optional pre-configured AI DEMO that showcases object detection in images, demonstrating the integration of machine learning in web apps.

Docs: (WIP) https://supeprojects.pages.dev/ (TODO)

JSR - GitHub - Known Issues - Wiki - Changelog - Roadmap

Contributing - Code of Conduct - License

Note

The created project is client-only. You are welcome to combine Supe Project Creator with any other server framework, such as Express.JS, FastAPI, Cloudflare Workers, etc.

For a bit of technical detail: how it does all of that is thanks to the built-in TypeScript compilers in the new runtimes. This approach uses globally installed http-server, nodemon, and esbuild packages, eliminating the need for additional dependency downloads.

Caution

The package is not production-ready yet.

Key Features - What can Supe Project Creator do?

Why choose Supe Project Creator over all the other project creators out there?

By utilizing Supe Project Creator, you can:

• Keep it Simple: For people who want to start a fresh project with nothing, but still have everything. No dependencies will be in the generated project package.json/deno.json files, additionally all the source code that powers your app will be right there, allowing you to truly fully customize your application and take it in any direction.
• Save Time: Skip tedious configuration tasks and jumpstart your project with a pre-configured template.
• Boost Efficiency: Focus on writing code, not setting up your project structure.
• Streamline Your Workflow: Take advantage of hot reloading and instant feedback to accelerate your development process.
• Explore New Possibilities: Leverage the included optional AI demo to experiment with machine learning in your web applications, or start with a clean project.
• Lightning-Fast Project Setup: Quickly create new projects with our intuitive scaffolding tool. Start with a pre-configured project structure, hot reloading, and optimized development tools.
• Customizable and Configurable: Adapt your project setup to your specific needs with flexible options and configurations. No reliance on third-party modules - you maintain full control over your environment.
• Comprehensive TypeScript Support: Enjoy full TypeScript support, including ESNext, ESM, Bun, and Deno, for an efficient, strongly-typed development process. The tool also features built-in error tracking and real-time updates.
• Built-in HTTP Web Server: Easily serve your project using the built-in web server that supports HTTP for development. This allows quick local testing of your project with minimal setup.
• Optional AI Demo Integration: Explore the potential of AI with our pre-configured demo, if you want, which features an object detection system that can recognize items in images - ideal for machine learning demonstrations or real-world AI projects.
• Blazing-Fast Performance with Intelligent Workflow: Experience ultra-fast startup times that keep your development flow uninterrupted. Our intelligent development tool minimizes unnecessary browser launches and manual configurations, allowing you to focus on coding. Enjoy optimized browser handling that adapts to your workflow, making it easier than ever to create and test your projects in real-time.
• Instant Hot Reloading for Real-Time Development: Leverage powerful hot reloading capabilities that instantly refresh your website as you make changes. This feature allows you to see updates in real-time, enhancing your productivity by eliminating the need for manual refreshes. Enjoy a smooth development experience with immediate feedback, so you can iterate quickly and efficiently.

With Supe Project Creator, you can concentrate on what matters most – building innovative and effective web applications.

Prerequisites - What do you need to run Supe Project Creator?

Before executing any scripts, please take a moment to:

1. Read this entire document to understand the necessary steps and requirements.
2. Verify that you have installed the required runtime: bun | deno 2 | node
3. Install recommended extensions: Follow the instructions below and install Deno if you plan to use it.

Warning

Deno support for this package is currently actively worked on. Node support will probably never work due to a missing built-in TypeScript compiler.

Tip

Recommended Extensions for Visual Studio Code

• Deno: The official Deno extension for Visual Studio Code provides features like syntax highlighting, code completion, linting, and debugging support for Deno projects.
  Install Deno

• Biome: A fast and flexible linter, formatter, and style checker for JavaScript, TypeScript, JSON, and more, ensuring clean and consistent code formatting.
  Install Biome

• JavaScript and TypeScript Nightly: Access nightly builds of the TypeScript language service, allowing you to use the latest features and fixes.
  Install JavaScript and TypeScript Nightly

Manual Installation Steps:

1. Open VSCode and navigate to Extensions (Ctrl + Shift + X).
2. Search for the name of the desired extension (e.g., "Deno", "Biome", or "JavaScript and TypeScript Nightly").
3. Select the extension and click Install.

🛠 Getting Started - Usage - Quickstart - Tutorial

To start using Supe Project Creator, simply run the following command:

Create a Clean Project in the Current Working Directory:

deno jsr:@supeprojects/[email protected] --name @example/my-supe-project --runtime deno
# or..
deno jsr:@supeprojects/[email protected] -n @example/my-supe-project -r deno
# or..
deno jsr:@supeprojects/[email protected] -n my-supe-project -r bun

cd @example+my-supe-project
# or..
cd my-supe-project
# or..
Open *.code-workspace

Create an AI Demo Project in the Current Working Directory using the --demo flag:

deno jsr:@supeprojects/[email protected] --demo --name @example/cat-dog-detector --runtime deno
# or..
deno jsr:@supeprojects/[email protected] -d -n @example/cat-dog-detector -r deno
# or..
deno jsr:@supeprojects/[email protected] -d -n cat-dog-detector -r bun

cd @example+cat-dog-detector
# or..
cd cat-dog-detector
# or..
Open *.code-workspace

Important

Supe Project Creator does not require a separate installation step. Simply execute the command above to create a new project instantly.

Once you're inside the project directory, you can then follow the steps to install dependencies and start the development server:

1. Install Dependencies:

bun install
# or..
deno install

2. Start the Development Server:

bun start
# or..
deno run start

Now a new browser tab will open, directing you to http://localhost if it isn't already open. This allows you to immediately view and interact with your project in your web browser.

This behavior is, of course, configurable in hotreload/config.ts, allowing you to customize the browser launch, hot reload, port or other settings according to your project's requirements.

CLI Options

To view the available options for Supe Project Creator, run the following command:

deno jsr:@supeprojects/[email protected] --help

• -h, --help: Displays help information.
• -v, --version: Displays the version number.
• -n, --name <string>: Sets the project name (required).
• -r, --runtime <deno|bun|node>: Specifies the JavaScript runtime environment (required).
• -d, --demo: Creates a demo project (default: false).

Project Structure - What Supe Project Creator generated projects have?

Supe Project Creator organizes your project using the following structure:

• src: Contains the project's source code (TypeScript).
• public: Public-facing files, including index.html.
• hotreload: Configuration and scripts for hot reloading.

Tip

Recommended VSCode Workspace Configuration:

To enhance your development experience, use the provided recommended .code-workspace file named after your project. This configuration excludes unnecessary files from view, allowing you to focus on your code.

Opening the VSCode Workspace:

1. Locate the <project-name>.code-workspace file in your project directory.
2. Double-click the file to open it in VS Code, or find "Open Workspace" inside VS Code.

Benefits of Using the Recommended VSCode Workspace:

• Streamlined view: Concentrate on your project's essential files, without clutter from node_modules and other irrelevant directories.
• Improved performance: By excluding unnecessary files, you'll experience faster loading times and more efficient search results.

Building for Production - How can you publish the website into a domain?

The public directory contains static files that can be hosted on any platform, In this example we will use Cloudflare Pages, Make sure you have a Cloudflare account, It's free.

1. To avoid modifying the public directory every time you want to push into production, and before this gets automated, it is recommended that you simply copy the folder public to dist and do the changes there.

2. The hot reload script is not needed in production, In the future this part will be automated but for now delete the generated dist/hotreload.js file, And remove the link for that file in dist/index.html:

+<script type="module" id="index-script"></script>
-<script type="module" id="hotreload-script"></script>
<script>
+    document.getElementById('index-script').src = `index.js?t=${Date.now()}`;
-    document.getElementById('hotreload-script').src = `hotreload.js?t=${Date.now()}`;
</script>

3. Now simply run the following command, customizing it to your needs:

npx wrangler pages deploy ./dist --project-name=mysupeproject

On the first time you use this command, it will prompt you to grant permission for wrangler to access your Cloudflare account, Wrangler was created by Cloudflare.

You can also add this script to your package.json/deno.json scripts.

The following command will produce a domain that will be available after a few minutes, for example <your-project-name>.pages.dev - Make sure you choose a name that is not taken.

You can easily add a custom domain in your Cloudflare account and manage your deployments via the Cloudflare dashboard > Workers & Pages

Programmatic Usage

The Supe Project Creator (SPC) can be utilized programmatically within your TypeScript or JavaScript applications. This allows you to create projects dynamically and customize the initialization process according to your needs.

Benefits of Programmatic Use

Utilizing SPC programmatically allows you to:

• Automate Project Creation: Integrate project setup into your build scripts or development tools.
• Streamlined Workflow: Enhance your development workflow by reducing manual steps in project creation.

Importing and Installing Supe Project Creator

Programmatic Use Example

import SPC from 'jsr:@supeprojects/[email protected]';

console.log("Testing SPC programmatically...");

// Display the help menu
SPC([]);

// Create a new clean project named "my-example-project"
SPC(['--name', '@example/my-example-project', '--runtime', 'deno']);

// Create a project with specific runtime and additional options (May soon be replaced with an argument instead of a variable)
SPC(['--name', '@example/my-custom-project', '--runtime', 'deno']);

// Generate a project and immediately start the development server - Not implemented yet! TODO: Implement --start script
// SPC(['--name', '@example/my-fast-project', '--start', '--runtime', 'deno']);

Programmatic Use Parameters

• argv: string[]: An array of command-line arguments that control the behavior of the project creation process. This includes options like --name for naming the project, and the --runtime option to specify the environment (e.g., bun, deno, or node).

For more detailed information on available options and flags, refer to the CLI Options section of the documentation.

Depending on the runtime environment you're using, you can import the Supe Project Creator (SPC) in different ways. Below are examples for Deno, Node, and Bun.

With these commands, you can easily set up and utilize the Supe Project Creator in your Deno, Node.js, or Bun environments. This flexibility allows you to choose the runtime that best fits your project needs.

Deno

To add the Supe Project Creator package in Deno, you can import it directly without any installation if you use the jsr: prefix in your import:

import * as SPC from "jsr:@supeprojects/[email protected]";

// Example usage
console.log("Testing SPC in Deno...");
SPC([]); // Shows the help menu

Alternatively, if you prefer to add it, use the following command:

deno add jsr:@supeprojects/[email protected]

Then, you can import it like this:

import * as SPC from "@supeprojects/supe-project-creator";

// Example usage
console.log("Testing SPC in Deno...");
SPC([]); // Shows the help menu

Bun

To add the package in Bun, use the following command:

bunx jsr add @supeprojects/supe-project-creator

Import the module in your Bun project:

import * as SPC from "@supeprojects/supe-project-creator";

// Example usage
console.log("Testing SPC in Bun...");
SPC([]); // Shows the help menu

Node.js

For Node.js, you can install the package using npx:

npx jsr add @supeprojects/supe-project-creator

Then, import it in your code:

import * as SPC from "@supeprojects/supe-project-creator";

// Example usage
console.log("Testing SPC in Node...");
SPC([]); // Shows the help menu

License

MIT License

Copyright (c) 2024 Burgil

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.

Contributors - Who helped build Supe Project Creator?

• Burgil

Released - When Supe Project Creater was released?

• 16 October 2024