Seed Quickstart with Webpack

I want to write fast, reliable and efficient web apps. Quickly.
And I like Rust and documentation.

!!! New Rust-only quickstart in development! => Seeder !!!

LIVE DEMO: quickstart-webpack.seed-rs.org

Main components:

• Seed - Rust framework, inspired by Elm. Seed's Awesome list.
• Tailwind CSS - CSS framework. All CSS classes in your project are typed for safe use in Rust code. Unused classes are automatically deleted for much smaller bundle size.
• Webpack - Bundler. Auto-reload on code change, dev-server accessible from mobile phones, prerendering for static websites... and many more useful features are prepared for you in this quickstart.
  • Why Webpack instead of Rust-only build pipeline? - Wiki
• Production-ready starter project - Example project is based on the website with several pages, favicons, nice fonts, meta tags for social media, buttons for scrolling to top, header which is hidden on scrolling, etc. It can be prerendered, but it also contains loading screen. For more complex project (based on another quickstart) see seed-rs-realworld.
• Production-ready configuration - Project is linted, compiled, prerendered and deployed in CI pipeline (see .github/workflows/main.yml and netlify.toml). Linters are very strict.

Zero to Hero

How to create your new app, modify it and deploy it - step by step guide.

1. Create a new project

I want to show you how to create, build and host your website for free, so we will need a public GitHub repository.

1. The simplest way how to do it is to click on the green button Use this template on the GitHub profile of this quickstart.

2. Make sure Git doesn't automatically convert your newlines to CLRF because linters don't like it.

   • Run $ git config --global core.autocrlf in your terminal and it should return input or false. See Git docs for more info.

3. Clone your new repository to your local machine. I use GitKraken, but you are probably better developer than me - use your favorite terminal.

2. Install / check required tools

1. Make sure you have basic tools installed:

   • Yarn - run $ yarn -v in terminal. It should output something like 1.22.4
   • Node.js - $ node -v => v12.13.0
   • Rust - $ rustc -V => rustc 1.43.1 (8d69840ab 2020-05-04)
   • Rust target wasm - $ rustup target list => .. wasm32-unknown-unknown (installed) ..
     • Install: $ rustup target add wasm32-unknown-unknown

2. Platform-specific tools like ssl and pkg-config:

   • Follow recommendations in build errors (during the next chapter).
   • Note: Don't hesitate to write a tutorial and create PR or write a Wiki page for your platform.

3. These tools are required by some commands:

   • wasm-pack

     • Check: $ wasm-pack -V => wasm-pack 0.9.1
     • Install: $ cargo install wasm-pack

   • cargo-make

     • Check: $ cargo make -V => cargo-make 0.30.7
     • Install: $ cargo install cargo-make

   • nightly rustfmt

     • Check: $ cargo +nightly fmt -- -V => rustfmt 1.4.14-nightly (a5cb5d26 2020-04-14)
     • Install:
       1. $ rustup toolchain install nightly
       2. $ rustup component add rustfmt --toolchain nightly

3. Prepare your project for work

1. Open terminal in your project
2. Install Webpack and other dependencies - $ yarn
3. Try to start dev-server - $ yarn start - and then open localhost:8000 in a browser.
4. Stop server (try Ctrl+c).
5. Try to lint your project - $ cargo make verify_only - you shouldn't see any errors.
6. Modify files like LICENCE, README.md and Cargo.toml as you wish and push changes into GitHub.

4. Write your website

1. Open project in your favorite IDE. I use IntelliJ or VS Code.
2. Run $ yarn start in terminal.
3. Open localhost:8000 in a browser.
4. You can open it also in your mobile phone:
   1. Make sure your dev-server aka computer is in the same network as your phone.
   2. Find out your local IP address. Use e.g. this online tool: https://www.whatismybrowser.com/detect/what-is-my-local-ip-address.
   3. Open URL with found IP address and default port (e.g. 192.168.1.5:8000) on your phone.

Note: You don't have to follow all steps below - reuse starter project code as you need.

Header

1. Open src/page/partial/header.rs in your IDE.
2. Delete function header_visibility.
3. Write a new body for function view.

Footer

1. Open src/page/partial/footer.rs in your IDE.
2. Write a new body for function view.

404

1. Open src/page/not_found.rs in your IDE.
2. Write a new body for function view.

Home page

1. Open src/page/home.rs in your IDE.
2. Write a new body for function view.

About page

1. Open src/page/about.rs in your IDE.
2. Write a new body for function view.

App core

1. Open src/lib.rs in your IDE.
2. Change TITLE_SUFFIX value.
3. Delete MAIL_TO_KAVIK and MAIL_TO_HELLWEB.
4. Write a new body for function view.

Favicons

1. Delete or replace files in /favicons.
2. Open static/templates/favicons.hbs in your IDE.
3. Delete content or update it.
   • Note: Templates are written in Handlebars.

Loading page

1. Open static/templates/loading_page.hbs in your IDE.
2. Delete content or update it.

Social media & basic settings

1. Open static/templates/social_media.hbs in your IDE.
2. Delete content or update it.

Basic HTML

1. Open static/index.hbs in your IDE.
2. Update content.

Fonts

1. Delete or replace files and directories in static/fonts.
2. Open /css/fonts.css in your IDE.
3. Delete content or update it.

Images & other files

1. Delete or replace files in static/images.
2. Delete static/Martin_Kavik_resume.pdf.

TailwindCSS

1. Open tailwind.config.js in your IDE.
2. Update content or replace it with the default one:

module.exports = {
  theme: {},
  variants: {},
  plugins: []
};

Custom CSS

1. Open /css/custom.css in your IDE.
2. Delete content or update it.

5. Prepare your project for deploy

How to format, lint and test your project.

And how to setup Github Actions with deploy into Netlify.

Formatter & Linter

1. Format: $ cargo make fmt (it overwrites files) or only $ cargo make fmt_check
2. You can modify format settings in:
   • rustfmt.toml
   • Makefile.toml - tasks fmt and fmt_check
3. Lint: $ cargo make clippy
4. You can modify linter settings in:
   • Makefile.toml - task clippy

Testing

1. Run $ cargo make test_h firefox for headless testing in Firefox.
   • There are more similar commands - see Makefile.toml
   • Note: There is only one test in this project (tests/test.rs), see seed-rs-realworld for more examples.
2. If you want to test prerendered website:
   1. $ yarn build:prerender
   2. $ yarn serve:dist
   3. Open localhost:8000 in a browser.
   4. Tip: Always test it also in production environment because e.g. routing is a little bit different among servers.
3. Always run $ cargo make verify before push to make sure CI pipeline will accept your code.
   • It'll format your code, lint it and start headless tests in Firefox.
   • You can change its behaviour in Makefile.tom - task verify (similar task verify_only is used in CI).

Netlify

1. Create a new Netlify site.
2. [Optional] Change site name or/and use your own domain.
3. [Optional] Turn on HTTPS.
4. [Optional] Add badge to project's /README.md (Site detail > Settings > General > Status badges).
5. Note somewhere Site id (Site detail > Settings > General > API ID)
6. Create and note somewhere Access token (Click on your avatar > User settings > Applications > New access token > Name it for instance GitHub)
7. [Optional] Adjust /netlify.toml to suit your needs. Netlify docs.

Github Actions

1. Open your GitHub repository in your favorite browser.
2. Click on Settings and then on Secrets.
3. Add secret NETLIFY_SITE_ID and set it's value to Site id.
4. Add secret NETLIFY_ACCESS_TOKEN and set it's value to Access token.
5. Click on Actions in the side menu and make sure that Actions are enabled.
6. [Optional] Modify /.github/workflows/main.yml.
   • Replace yarn build:prerender with yarn build:release if you don't want to prerender pages.
7. [Optional] Push your code and switch to tab Actions to check that everything works.

Manual Deployment

1. Run yarn build:realease.
2. Check if build works by running yarn serve:dist and view in a browser.
3. Deploy the contents of the dist directory to a web server.

Travis CI

6. Add your project to Awesome list

1. Create PR or issue in awesome-seed-rs.

Used in projects

• seed-rs/seed-rs.org
• MartinKavik/kavik.cz
• [create PR or Issue]

Contributing

• Improved documentation, fixed typos, updated dependencies, ... - create Issue or PR.
• Ideas, bugs, questions, ... - create Issue.

Note: Please squash commits and rebase before creating PR. Thanks!

Other Seed projects

• seed-rs/awesome-seed-rs