https://github.com/jonasfroeller/webpack-webapp

Webpack frontend-webapp starter.
https://github.com/jonasfroeller/webpack-webapp

asciidoc docker docs fonts gh-pages images isc-license jest-tests postcss scss shoelace tailwindcss ts web-components webpack5 workflow

Last synced: about 1 month ago
JSON representation

Webpack frontend-webapp starter.

• Host: GitHub
• URL: https://github.com/jonasfroeller/webpack-webapp
• Owner: jonasfroeller
• License: isc
• Created: 2023-12-02T11:48:57.000Z (about 1 year ago)
• Default Branch: main
• Last Pushed: 2024-01-12T20:27:29.000Z (12 months ago)
• Last Synced: 2024-01-13T11:03:24.107Z (12 months ago)
• Topics: asciidoc, docker, docs, fonts, gh-pages, images, isc-license, jest-tests, postcss, scss, shoelace, tailwindcss, ts, web-components, webpack5, workflow
• Language: TypeScript
• Homepage: https://jonasfroeller.github.io/webpack-webapp/
• Size: 919 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# webpack-webapp

Webpack frontend web app starter.  

Includes: Hosting(gh-pages), Testing(Jest), CICD(Husky, GitHub Actions, Docker), Docs (.adoc), asset handling(Images, Videos, Audios, Fonts...), TypeScript, Sass, TailwindCSS, Web Components(lit), Component Library(shoelace).  

The goal is to keep the bundle size as small as possible but still have a decent developer experience.

## Workflow

### Images, Videos, Audios, Fonts (`public/lib/assets`)

You could also put them inside of `public/static` and import them with `/`, but if you do so, caching might cause you headaches.  

(if in `public/lib/assets` the assets are given a unique hash at build time, if in `public/static` they are just copied to the root of the build folder)

### Icons

Shoelace comes with a lot of icons: https://shoelace.style/components/icon.

### Components (`public/lib/components`)

#### Custom(Lit)

Reusable elements (components) should be written in TypeScript for type safety.  

They are then imported into the `.html` file as follows:

```html

```

#### Shoelace

If you don't want to use shoelace, you can delete the `shoelace` folder, delete the following in your `webpack.config.js` file to reduce the bundle size:

```js

module.exports = {

    ...

    plugins: [

        ...

        new CopyPlugin({

            patterns: [

                {

                from: path.resolve(

                    __dirname,

                    'node_modules/@shoelace-style/shoelace/dist/assets',

                ),

                to: path.resolve(__dirname, 'dist/shoelace/assets'),

                },

            ],

        }),

        ...

    ]

    ...

}

```

##### Importing Shoelace Components in your .js files

```js

// ShoelaceUI

import '@shoelace-style/shoelace/dist/themes/light.css';

import '@shoelace-style/shoelace/dist/themes/dark.css';

import '@shoelace-style/shoelace/dist/components//.js';

import {setBasePath} from '@shoelace-style/shoelace/dist/utilities/base-path.js';

setBasePath('/dist/shoelace');

```

##### Using Shoelace Components in your .html files

```html

>>

```

### Scripts (`public/lib/script`)

Page-specific scripts in `public/lib/script/pages`.

#### How to Use Them?

```js

module.exports = {

    // INFO: include the script in the build

    ...

    entry: {

        ...

        : './public/lib/script/pages/.js',

        ...

    },

    ...

    // INFO: import the `script/pages` script in its html template

    plugins: [

        ...

        new HtmlWebpackPlugin({

            filename: '.html',

            template: 'public/routes/.html',

            chunks: [''], // only include the '' chunk

        }),

        ...

    ]

    ...

}

```

### Styles (`public/lib/style`)

[Tailwind](https://tailwindcss.com/) extensions in `main.css`.  

**Suggestion**: Custom CSS in [SCSS](https://sass-lang.com/documentation/syntax/) syntax and [BEM](https://getbem.com/introduction/).  

General custom CSS: `style.scss`  

Component Specific/Custom Class: `.scss`

### Routes/Static Sites, Templates (`public/routes`)

This is where you put your HTML templates.  

Pure HTML only, no JS, and no CSS (except for TailwindCSS classes).

### Static Elements (robots.txt, favicon.ico...) (`public/static`)

These are moved to the root of the `dist` folder.

### Docs (`docs`)

You can write them in AsciiDoc format.  

They are automatically converted to HTML and moved to the root of the `dist/docs` folder.

### NPM Packages

Don't forget to install the dependencies with `--save-dev` or `-D` if they are only used for development.  

Production dependencies should be as slim as possible, because that is the goal of using webpack and not some large framework.  

(Currently only Express as the NodeJS server and Cors for setting Cors headers for the backend is installed as a production dependency.)

## CICD

### GitHub Actions

The workflow is defined in `.github/workflows/cicd.yml`.

It is triggered on every push to the `main` branch.  

**jobs**: 

* `test-and-build-frontend`,

* `push-frontend-to-docker-hub` (don't forget to set ``DOCKERHUB_USERNAME`` and ``DOCKERHUB_TOKEN`` as secrets  

in the repo settings AND change the image name in the workflow file to your own (example: ).),

* `publish-frontend-to-github-pages`

### Locally (Husky)

A `pre-commit` hook is defined in `.husky/pre-commit` (formats code).  

A `pre-push` hook is defined in `.husky/pre-push` (lints code).  

You can disable them by adding `--no-verify` to your commit/push command or by deleting  

the `.husky` folder or you could simply update the file to your liking.

## Build Config (`webpack.config.js`)

You can find the build config in `webpack.config.js`.

## Testing

### Jest

You can find the Jest config in `jest.config.js`.  

You can write the Jest tests in `public/lib/script/__tests__`.

## Commands (`package.json(.scripts)`)

Start Webpack development server:

```bash

npm dev

```

Build/bundle for production:

```bash

npm build

```

Preview the bundle:

```bash

npm preview

```