User Guide
user guide / cookbook / “field guide” field guide / recipes
FERC / webcraft
this section includes practical “go-to” / endorsed solutions for common (problems) using this toolkit. the technology used isn’t always necessarily part of the toolkit, but they’re my “if you asked me how to do ____, this is what i’d do” solutions.
smaller tutorials for how to do specific kinds of things
code snippet library
- code snippets for common patterns (mostly TW)
- ex: commonly needed tw markup (two column grid, hamburger menu, etc)
- not part of ui kit, but copy/paste code for doing specific things
a manual (/field guide) for building (effective/attractive/solid/usable) web sites/applications with as little (fanfare/suffering/pretense/) as possible
instructional guides and resources (links to valuable online tools/libraries that can help you solve problems quickly)
my “best-practices” guide for putting stuff together
- custom components
- validation - form & individual input
- how it works
- what to include (lib ref in js + novalidate on forms, arguments for components)
- validation types
- photo uploads
- requirements (bunny for now)
- how it works
- required db fields (photo_url, etc)
- gallery_content, etc
- single vs gallery
- upload paths
- component props (defaults, max files, file size, etc)
- crop params
- modals/alerts
- api reference / options
- form components (like a LinkForm) - “redirect” props (integrated w/ save buttons)
- admin tables etc
- backend components
- email send
- crud
- misc string formatters
- ?? anything else
- validation - form & individual input
- installation / init process
- kysely ref/reqs
- optional google app/oauth setup instructions
- how to set admin user? (prompt for admin user during setup?)
- sql for tables to create (script?)
- kysely how to set pw reqs (pw length, etc) (and how to show them?)
- other default tables (gallery_content, rel_users_roles, auth_roles, etc)
- ?? possible to create automatically from schema?
- general crud conventions for every table
- deleted_at (we do soft deletes by default)
- uuid
- created_at
- updated_at
- permissions logic (see config/auth.ts)
- difference in ownership types (simple, complex … direct vs relationship) - lib/auth/permissions.ts
- app config: config/app.ts
- notes
- we’ve really tried to make this accessible (forms, modals, alerts, etc) and have chosen tools that handle a11y responsibly (true?)
dw guide
- how to write/manage auth rules
- how to manage/update db schema
dw guide
- 3rd party service setup
- bunny cdn
- google client
- mysql
- smtp
better auth init & secret key gen
- https://www.better-auth.com/docs/reference/options#secret
- ?? cmds for db table / schema / migrations init
init commands for other tables
- gallery_photos
notes for what to add to db tables for photo uploads photo_url photo_url_parameters
resources want
- cool to have a ref in the docs/guide for migrations / schemas (data structures) for common things like blogs, podcast, profiles, etc
- specifically concerned w/ migrations at the moment (i’m writing some right now)
field guide - how to set up google apps for oauth login (& guides for any other 3rd-party service setup)
- workflow for making db changes
- update schema
- update db (ideally with a 3rd party script that can just look at the schema and make changes as needed)
- maintainer note
- need to keep the default schema for kysely (type definitions) and default schema migrations for better auth in sync as we add new default tables in the future
- src/config/schema.ts - Used by Kysely for type definitions and database operations in your application
- src/lib/auth/better.ts - Used by Better-Auth for managing tables and migrations
troubleshooting misc
dw guide - troubleshooting if you get this: “(node:16267) Warning: To load an ES module, set “type”: “module” in the package.json or use the .mjs extension.” don’t worry about it, that’s npm life baby BUT if you want to kill the warning, change this in package.json: “dev”: “node —no-warnings astro dev”,
dw guide - upgrading libs
- may need to upgrade flyon (if you care) as they make updates frequently - https://flyonui.com/docs/getting-started/upgrade/
- npm install flyonui@latest
external components - curated collection of resources
- nice stuff like - https://www.fancycomponents.dev/
guide - cool to have a ref of recommended services (for mailers, file hosts, etc)
potential services
- notifications service, transactional mailer - https://developers.brevo.com/
- w/ nodemailer - https://developers.brevo.com/docs/node-smtp-relay-example
docs - pattern for saving over multiple pages/forms
- documented convention / pattern for saving sections of stuff with multiple screens (like blu spaces)
- Save listings like this, separate horse data, photos, pedigree, ad details, pricing, etc on different screens (different forms, multiple templates, tab/subnav selected)
- Not everything needs to be saved this way, but it needs to be easy to do
REF - my first five minutes in astro - https://www.seancdavis.com/posts/my-first-five-minutes-in-astro/ tips on setting up a project, best practices for boilerplate, etc
guide / boilerplate for skeleton screens automatic skeleton screens ?? implement w/ “animated placeholder” components?
use the package - placeholders w/ astro - https://github.com/matheusbronca/astro-awaited - skeleton screens / placeholders ***
cookbook / field guide - similar to this - https://sergiodxa.github.io/remix-utils/? resources and stuff you’ll (i’ll) need frequently, commonly needed solutions (that don’t need to be included with EVERY project, but if you want tot do it with this sytem, this is THE way to do it)
building with dw - copypasta boilerplate
- some of these components/sections/functionality DO require a lot of code, but all the code is boring and the patterns are pretty obvious, you can find an existing pattern (admin/users index/edit/new/save/delete) and copy it, modify for your purposes
- front end / dev resources
- collection of cool “approved” libraries (ones that we like working with and yield badass results, ideally fitting the same license and ethos of the projects)
- front end best practices
- the workflows, resources and best practices i use/need to be a productive and efficient FE dev
- notes of all the tools i use for various things (unix time format, generating favicons, etc)
easy on-ramp for more “advanced” features (queues, real-time streaming, elastic search/meili , etc)