Skip to content

Latest commit

 

History

History
233 lines (155 loc) · 13.5 KB

README.md

File metadata and controls

233 lines (155 loc) · 13.5 KB
Raw

Plasttic

Plasttic Web Workflow

A methodology based Front-End development environment for Static Sites.

npm NPM Downloads LICENSE VOLTA Twitter Follow

About

Welcome! 🖖

Plasttic Web Workflow is a methodology based professional Front-End development environment for Static Sites: HTML and CSS/PostCSS boilerplate, CSS Reset, Atomic Design System, Typescript/Javascript, Dev Server/Build Tool, File structure, Conventions & Best Practices.

This is not a Bundler nor a Framework, though it has some of the features of a Bundler, and it includes tools and rules that will improve the development process and produce quality code, it's built to support a different development process.

This workflow is intended to be open, allowing the developer to adopt or customize the methodology with the objective of producing accessible, scalable and robust interfaces.

Note: The files installed are not empty. The reason is that, by creating a template, it's easier to demonstrate the methodology, concepts and conventions, and even building upon the existing code.

Workflow

Dev Server, Build Tool, File/Folder Structure, HTML Boilerplate, CSS Reset, Templates, Atomic Design CSS, Print CSS, ES Modules, Typescript, PostCSS, CSS Styling, HTML/CSS/JS Minification, Conventions, Linting, Testing, Image Optimization (Soon!)

Related projects

Table of Contents

Methodology

  • Core Fundamentals
  • Best Practices/Conventions
  • Performance/Core Web Vitals
  • Separation of Concerns
  • Documentation
  • Design System/Atomic Design
  • BEM/ABEM Methodology
  • CSS Reset
  • HTML Boilerplate
  • Semantic HTML/Accessibility
  • Progressive Enhancement
  • CSS/Postcss
  • Typescript/Javascript
  • Code Conventions/Linting
  • Debug/Test

Start

Quick Start

(cd into your projects folder)
npx create-plasttic
cd <project-name>
npm run start
  1. Creates a folder with the project name you defined
  2. Downloads and installs the latest version of Plasttic Web Workflow
  3. Installs all the project dependencies, Git hooks (Linting pre-commit), Playwright install

Typescript

  • npm run start installs Typescript globally *although it is installed as a devDependency, the Dev Scripts may not work as expected if you do not install it globally also.
  • TS-Reset is installed by default. If you wish to disable it, delete the reset.d.ts file.
  • Linting: Prettier ESLint (requires some configuration: see the plugin page and the Plasttic VSCode settings). Install ESLint to provide error and warning messages in the files.

Development

  • Run npm run dev to start the dev server on http://localhost:8000 *

  • Run npm run build when you are ready to publish *

  • *Source folder: src/, Dev folder: dev/, Build folder: dist/

Customizing

(Note: The files installed are not empty. The reason is that, by creating a template, it's easier to demonstrate the methodology, concepts and conventions, and even building upon the existing code.)

  • Search for "TODO:" in comments, relative to info that needs to be changed or checked. After, change it to "DONE:". If using VS Code, use the Todo Tree extension or TODO Highlight
  • If .##gitignore## exists, rename it to .gitignore and customize to your project info.
  • ⚠️ Do not delete, rename or move files in the root folder. Do not delete, move or rename folders in the src folder, except the templates folder. Do not delete or move the following files in assets folder: js/scripts.ts (you can rename to scripts.js), js/modules/module.ts (at least one file name.ts/.js must exist), css/styles.css and css/print.css (do not rename this CSS files) - this files must exist, even if empty. If not used, delete the corresponding tag in the HTML page. ⚠️

Development with https

  • Step 1: Run mkdir certs
  • Step 2: Run cd certs
  • Step 3: Install certificate with mkcert
  • Step 4: Check certificate filenames and/or path in the file browser-sync.cjs
  • Step 5: Run npm run dev:ssl to start the dev server on https://localhost:8000

Libraries

  • TS-Reset (If you wish to disable it, delete the reset.d.ts file.)
  • Zod

Linting

(Extends the editor File Type rules, .editorconfig and VS Code settings)

Files * Usage Result Config Plugin References
Prettier html, css, md, json On Save, Build Script, Pre Commit, Plugin Errors, Warnings and Fix .prettierrc, .prettierignore Prettier
ESLint js, ts (src/tests) On Save, Build Script, Pre Commit, Plugins Errors, Warnings and Fix .eslintrc.cjs, .eslintignore Prettier + ESLint, ESLint ** Airbnb, Airbnb Typescript, Wes Bos ESLint Setup
Stylelint css On Save, Build Script, Pre Commit, Plugin Warnings, Limited fixes and CSS sorting .stylelintrc.json Stylelint

*all linting is done on the src folder, except for ESLint that also lints the tests folder.
**see Typescript

Testing

About Usage Folders * Notes Plugins
Jest Unit nad Integration testing Build tool, Pull Request, Terminal (npx jest) dev, ci, reports Typescript support, Jest CLI Jest
Playwright End-to-End testing Build tool, Pull Request, Terminal dev, ci, reports Playwright Test for VSCode
Lighthouse Web Core Vitals npm run test:vitals:page --page=page.html reports
Unlighthouse Lighthouse website testing npm run test:vitals:site --url=https://example.com reports **

*This folders are inside the tests root folder separated by test app. For Jest and Playwright, the tests placed on the ci folder will run automatically on npm run build and on pull request and the dev folder is were individual tests are placed to run from the terminal with npx jest.
**The Unlighthouse reports folder .unlighthouse is located in the root directory.

Manual Install (Clone)

  • Step 1: Copy the repository git clone https://github.com/tojeiro-me/Plasttic.git

  • Step 2: Move the the contents of the package folder into your <project-folder>

  • Step 3: Run cd <project-folder>

  • Step 4: Rename .##gitignore## to .gitignore

  • Step 5: Run npm run start

    • Installs the needed dependencies
    • Installs Husky Git Hooks
    • Initializes Playwright

  • Step 6: Run npm run dev to start the dev server on http://localhost:8000 *

  • Step 7: Run npm run build when you are ready to publish *

  • *Source folder: src/, Dev folder: dev/, Build folder: dist/

Templates

Documentation

  • File Comments
  • Check docs folder 🚧
  • Documentation website (Soon!)

Please check the CHANGELOG for major or breaking changes

Links

  • Website 🚧
  • Documentation (Soon!)

Follow

Twitter Mastodon Github

License

Plasttic