zoucli

v1.5.3

Published

a year ago

Scaffold a custom Zou! SSG project with interactive prompt

Downloads

0High
0Medium
0Low

andikod

Zou CLI SSG Nunjucks SCSS OpenProps Hyperscript TailwindCSS TypeScript

Zou! CLI - SSG

Scaffold a custom Zou! SSG project and more, with interactive prompts.

— Prononced more or less like 'zoo' ... Zou! is a french interjection that stands for: JustDoIt! GoAhead! Let'sGo!

Simple SSG with close to zero configuration, going back to the basics.

No JS framework, no mega-bundler, almost nothing new to learn beyond HTML, CSS, JS yet it does the job "out of the box" . #HaveFun

| -Folder- | -Purpose- | | --- | --- | | Bin: | db.js will scan files and create an object from the Frontmatters | | Docs: | -if enabled- JS and SCSS docs websites will generate here. | | src/Data: | Add data in .js / load in zou.config.js / use in .njk templates | | src/Layouts: | General .njk templates, composed with partials and more | | src/Macros: | Styled components, functionalities, (many possibilities) | | src/Pages: | Extending a layout. The main element with dynamic content | | src/Partials: | Sub-pages to be included in others | | src/Scripts: | The enty points for the .js or .ts files | | src/Static: | Assets to be copied to public, generally images | | src/Styles: | SCSS (w/ subfolders partials) / Tailwind. Whatever flavor you like | | Tests | -if enabled- A default folder for thing.test.js files, but it's up to you |

PS: The package used to convert nunjucks is using cjs, so the zou.config.js is still using that syntax for the moment, but the main JS file is imported as Module, so we can go ESM there. At some point will eventually find a way to go fully ESM accros the board but things are working smoothly enough already.

Scaffold a new Zou! project, the "one liner way"

From v1.4.0, simulating "yes" answers to the propmt, a core SCSS+JS project will be instantly created.

The optional flags -vsc, -vim, -nvim at the end npx zou create myProj -y -vim will open the generated folder in VSCode, Vim or neoVim, so you could finish from there with your favorite package manager. Just pnpm/yarn/npm i then run dev.

npx zou create myWebsite -y

// or first: npm i -g zoucli ...then:
zou create myWebsite -y

To scaffold an instant Tailwind & JS Zou! project:

zou create myWebsite -tw

The full machine with Jest, JS TypesChecking via JSDoc, docs generation for both Javascript and SCSS via jsDoc and sassDoc, plus the rest of the Zou! features. To disable/enable types chacking, edit tsconfig.json file in the root.

zou create myProject -full

For TypeScript, don't use any flag and anwser to the prompt ;)

Talk to the prompt

No flags, just having a conversation:

zou create myWebsite

Zou! will ask:

That's it. Enjoy.

Pages database auto-generated from frontmatter

On npm run dev, npm run build or directly from the root with node bin/db, Zou! will scan the /public folder for .html pages, and transform the HTML-frontmatter into the 'pages' object, stored and exporterd from /src/data/db.js

Each frontmatter object expecting at least 'title' and 'url' (here the date is a timestamp for now) https://timestamp.online/

<!-- src/pages/blog/article-one/index.njk -->
{% block frontMatter %}
  title: Article One
  url: /blog/article-one
  date: 1701621848
  tags: [one, two, racoon]
{% endblock %}

becomes an entry in the pages object

// src/data/db.js
module.exports.pages = [
{
  "title": "Article One",
  "url": "/blog/article-one",
  "date": 1701621848,
  "tags": [
    "one",
    "two",
    "racoon"
  ]
}
]

then is injected into the 'data' object for .njk files

// zou.config.js

/* Import Data file*/       
const db = require('./src/data/db.js');

/* Create the data object */
const data = {
appName: 'myWebsite',
pages: db.pages,
};

Collections and more via custom Nunjucks filters

Navigation

Navigations lists of links are stored in src/data/nav.js like the navMain block:

// src/data/nav.js
module.exports.navMain = [
  {
    url: "/",
    label: "Home",
  },
  {
    url: "/blog",
    label: "Blog",
  },
];

Then made available to the templates in zou.config.js

// zou.config.js

/* Import Data file*/       
const nav = require('./src/data/nav.js');

/* Add to the data object */
const data = {
  appName: 'myWebsite',
  navMain: nav.navMain,
};

That way, in any template or partial like a header, we can just:

// someFile.njk

<ul>
{% for link in navMain %}
  <li><a href="{{ link.url }}">{{ link.label }}</a></li>
{% endfor %}
</ul>
};

We can duplicate the block in src/data/nav.js and repeat the rest of the steps, to create things like navFooter, navSocials or whatever other list.

SCSS Partials Subfolders

From 1.3.0, the SCSS files are organized in subfolders, inspired by the official 7-1 pattern, Kevin Powell and personnal preferences. The starting structure is:

  @use "abstract";
  @use "base";
  @use "components";
  @use "layout";
  @use "pages";
  @use "themes";
  @use "vendors";
  @use "utility";
  @use "freestyle";

The freestyle folder imports the _getWild.scss partial, for random stuff quickly thrown there while prototyping or for whatever reason. See it like the TypeScript's any:scss.

You can scaffold several Zou! projects, customize the SCSS folders and save them on github as starters with different structures.

Scaffold a new Page

From a terminal, just call:

zou make:file

The prompt will ask:

Save to Git

From the project's root folder:

zou git:save

It will prompt for a Commit message or generate one as Update from month/day at h:m, ask for the branch name and defaulting to master.

It will basically do (in one go) the equivalent of:

git add .
git commit -m "commitMessage"
git push origin branch

The basic "take everything and throw it on master", that's why it's called by a generic git:save like a Ctr/Cmd+S. Other git:commands might come later.

Manual Deploy to Vercel

From the project's root folder:

zou deploy:vercel

It will build the project, move into /public and call vercel deploy --prod. The first time it will setup the distant project or link to an existant, and the next ones will just upload the website.

If you have "strange characters" in the terminal, just do the first deploy directly by cd public && vercel deploy --prod. From here, the deploy:vercel from the root will roll. Nothing is "borken" just Bash commands running from Node via zh wraper.

Manual Deploy to Netlify

Be sure to have Netlify CLI installed: npm install netlify-cli -g.

zou deploy:netlify

It will build the project, move into /public and call netlify deploy --prod for a Manual Deploy.

One approach is to drop here the public/ folder after running npm run build the first time, and change the name on Netlify to match with your project. > Go inside the public/ folder, call netlify link and link them.

Next times from the root of your local project npx zou deploy:netlify will be enough, build & deploy simple command. To save your code ...zou git:save

Related Docs, just in case: Nunjucks, Openprops, Hyperscript, SCSS, zouMixins, Tailwind, Typescript.

Via zouMacros: AlpineJS, htmX, Pocketbase, ChotaCSS, BonsaiCSS, Bulma, Bootstrap Comming soon: Supabase, Planetscale.

Changelog

1.1.0

Added the deploy:vercel, deploy:netlify, git:save commands and fixed the postbuild script.

1.1.1

Fixed some misspelled filenames causing troubles with Tailwind & Typescript. It's fine now.

1.2.0

Added FrontMatter support to the pages in the templates
Automatic 'database' object with the data from the frontmatter
Collections, Tags, limitFromTo(), withTag('something'), ... Nunjucks filters
Navigation objects generating navMain, navFooter,...
and maybe other things I can't remenber

1.2.2

Fixed the commit message from the zou git:save command. It displayed the default message instead of the custom one, it's now back to normal.

1.3.0

SCSS files are now organized in 7-1 SASS inspired folders, imported into main.scss using the @forward/@use pattern. Use it as a starting point, of have fun "freestyling into the getWild zone" ;)

1.4.0

:: Aditions

Oneliner options to instantly scaffold projects with flags:
zou create myProject -y -vsc : SCSS + JS project and open it in VSCode
zou create myProject -tw -vsc : Tailwind + JS project and open it in VSCode
zou create myProject -full -vsc : SCSS/JS/Jest/JSDoc/sassDoc project and open it in VSCode
Without the -vsc flag, everything is still instantly created, you can just cd myProject.
Generally speaking, JS Testing & TypeChecking plus Docs generation are added as options.

:: Deprecation

The 'Play with CDN' prompt is removed, as we can simply use {{cdn.pkg('whatever')}} from within a layout folder, and having a select form would be a nightmare to maintain. Just check zouMacros for the available packages list.

1.5.0