cayo 0.9.10 → 1.0.0

package/docs/config-reference.md

@@ -0,0 +1,349 @@
+# Config Reference
+
+## Config File
+
+Cayo is not "zero config" because it does require a particular [project structure](../README.md#project-structure), but it does support having _no config file_. However, adding a `cayo.config.js` file to your project allows you to configure most of the things that Cayo needs & expects, such as paths for pages, components, and even the template filename.
+
+### Example
+```js
+// cayo.config.js
+export default {
+  // config options
+  pages: 'outputs',    // default: 'pages'
+  components: 'cayos', // default: 'components'
+  build: {
+    outDir: 'build',   // default: 'dist'
+  },
+  svelte: {
+    // Svelte options, e.g., for defining preprocessors for svelte.preprocess
+  },
+  vite: {
+    // Vite options, like server.port
+    server: {
+      port: 1234
+    },
+    rollupOptions: {
+      // Rollup options, like plugins
+    }
+  }
+}
+```
+
+Check out [more config examples](#more-examples).
+
+## Cayo Options
+
+### projectRoot
+- **Type**: `string`
+- **Default**: `'.'`
+
+The project root directory, where Cayo will look for the required project structure. Can be an absolute path or a directory relative to the current working directory. 
+
+---
+
+### src
+- **Type**: `string`
+- **Default**: `'src'`
+
+Specify the directory where your source files will be, relative to the [project root](#projectroot). This folder will be watched for changes during dev. 
+
+---
+
+### pages
+- **Type**: `string`
+- **Default**: `'pages'`
+
+Specify the directory where your page components will be, relative to `src`. These can also just be thought of as "inputs" for the HTML that is generated as output. 
+
+---
+
+### components
+- **Type**: `string`
+- **Default**: `'components'`
+
+Specify the directory where your Cayo Components will be, relative to `src`. Cayo will expect any `<name>.cayo.svelte` that is to be rendered on a page to be in this directory. Other components are not required to be in this directory, but can be. 
+
+---
+
+### publicDir
+- **Type**: `string`
+- **Default**: `'public'`
+
+> **Note**<br>
+> Use this option _instead_ of Vite's `publicDir` option. We pass it to Vite, but also use it internally within Cayo processes.
+
+Specify the directory to be used as the public directory, which is used to serve static assets during development and copied into the `build.outDir` during build. 
+
+This is where your static assets will go, such as images, `favicon.ico`, and any static JS dependencies.
+
+You will be able to reference any of these assets with a leading `/` in your markup. 
+
+**For example:** assuming you haven't changed the default, and you have this in your project root:
+
+```
+src/
+└ pages/
+  └ index.svelte
+public/
+└ some.png
+```
+
+```svelte
+<!-- index.svelte -->
+<img src="/some.png">
+```
+
+Read about how the [public directory works in Vite](https://vitejs.dev/guide/assets.html#the-public-directory).
+
+---
+
+### base
+- **Type**: `string`
+- **Default**: `'/'`
+
+> **Note**<br>
+> Use this option _instead_ of Vite's `base` option. We pass it to Vite, but also use it internally within Cayo processes.
+
+Base public path when served in development or production.
+
+<!-- TODO: add more details -->
+
+Since this option is passed to Vite, read more about it in the [Vite docs](https://vitejs.dev/config/shared-options.html#base).
+
+---
+
+### build.outDir
+- **Type**: `string`
+- **Default**: `'dist'`
+
+Specify the output directory, relative to the [project root](#projectroot).
+
+---
+
+### build.assetsDir
+- **Type**: `string`
+- **Default**: `'assets'`
+
+Specify where the assets generated by Cayo should be placed within your output, relative to `build.outDir`.
+
+---
+
+### css.internal
+- **Type**: `boolean`
+- **Default**: `false`
+
+If set to `true`, this will inject a page's CSS inside `<style>` elements, in place of `<link>` elements.
+
+This will only affect the component-scoped CSS you define in a Svelte component (or page), and any CSS imported in an entry file.
+
+---
+
+### cayoPath
+- **Type**: `string`
+- **Default**: `'.cayo'`
+
+Specify the Cayo output directory that is used for Cayo processes. Cayo outputs files into this folder, and it's contents are either served during `cayo dev` or used to build your project during `cayo build`. 
+
+---
+
+### cayoComponentInfix
+- **Type**: `string`
+- **Default**: `'cayo'`
+
+Specify the Cayo Component infix that is used to identify by Cayo's processes (Note: `<name>.<infix>.<extension>`). By default, a Cayo looks like: `some.cayo.svelte`. If you changed this option's value to `'fancy'`, your Cayo would need to be named `some.fancy.svelte`.
+
+---
+
+### templateName
+- **Type**: `string`
+- **Default**: `'__template'`
+
+Specify the name of the template file. This is **_not_** a path; Cayo will always expect this filename to be at the root of the `src` directory (e.g., `src/__template.svelte`). The extension, `.svelte` should not be included in this option's value. 
+
+---
+
+### mode
+- **Type**: `string | false`
+- **Default**: `'development'`
+
+By default, the mode will be `development` during `cayo dev` and `production` during `cayo build`. This option can be used to override the default mode, and will be used for both commands.
+
+---
+
+### debug
+- **Type**: `boolean`
+- **Default**: `false`
+
+Useful for seeing more output when running `cayo`.
+
+> **Note**<br>
+> This option is experimental and may be removed in the future.
+
+---
+
+## Svelte Options
+
+There are a few options that Cayo passes to Svelte (consumed by `rollup-plugin-svelte`):
+- [preprocess](#sveltepreprocess)
+- [compilerOptions](#sveltecompileroptions)
+<!-- TODO: - [extensions](#svelteextensions) -->
+
+Svelte options are passed via the Cayo config:
+```js
+// cayo.config.js
+export default {
+  svelte: {
+    preprocess: [
+      // define custom preprocessors for Svelte to use
+    ],
+    compilerOptions: {
+      // define compiler options for Svelte to use
+    }
+  }
+}
+```
+
+---
+
+### svelte.preprocess
+- **Type**: `<SveltePreprocessor> | Array<SveltePreprocessor>`
+- **Default**: `[]`
+
+Passed to the Svelte Rollup plugin, but is appended to an array of Cayo's internally defined preprocessors (which is only [`svelte-preprocess`](https://github.com/sveltejs/svelte-preprocess)). [See plugin options](https://github.com/sveltejs/rollup-plugin-svelte#usage).
+
+---
+
+### svelte.compilerOptions
+- **Type**: `object` _(of options)_
+- **Default**: `{}`
+
+There are a few options that Cayo needs to control in order to work, so changing them will have no effect: `compilerOptions.generate` and `compilerOptions.hydratable`. All other options will be passed to the Svelte Rollup plugin. [See plugin options](https://github.com/sveltejs/rollup-plugin-svelte#usage).
+
+---
+
+## Vite Options
+
+Not all Vite options are directly used by Cayo. Most of them are passed to the dev process, which uses `vite dev`. `vite.build.rollupOptions` is the only Vite-specific option passed during both `cayo dev` and `cayo build`. 
+
+> **Note**<br>
+> Cayo shares some options with Vite, such as `publicDir` and `base` and `root` (as `projectRoot`). These should be defined at top level of your Cayo config, not in the `vite` option object, but will be passed to Vite as needed.
+
+Vite options are passed via the Cayo config:
+```js
+// cayo.config.js
+export default {
+  vite: {
+    server: {
+      // server options, like port
+    }
+    build: {
+      // rollupOptions is the only passed vite.build option
+      rollupOptions: {
+      // define Rollup options to be used for dev and build, like plugins
+    },
+    // other Vite options...
+  }
+}
+```
+
+During `cayo dev`, Cayo defines a few Vite options internally, which cannot be overridden:
+- `configFile: false`
+
+## Rollup Options
+
+Options for Rollup should be passed to Cayo via the `vite.build.rollupOptions` object. The only Rollup config option that Cayo uses internally is `vite.build.rollupOptions.plugins`, but the entire `rollupOptions` object is passed to Vite while running the dev server and during build.
+
+## More Examples
+
+### Customize `svelte-preprocess`
+To add options to Svelte Preprocess, install `svelte-preprocess` locally, and then pass the preprocessor(s) in your Cayo config with options:
+```js
+// cayo.config.js
+import sveltePreprocess from 'svelte-preprocess';
+export default {
+  svelte {
+    preprocess: [
+      sveltePreprocess({
+        // Learn more about the options you can pass here:
+        // https://github.com/sveltejs/svelte-preprocess/blob/main/docs/preprocessing.md
+        markupTagName: 'content',
+        replace: [['Jane', 'Cool'], ['Doe', 'Cat']]
+      }),
+    ],
+  }
+}
+```
+---
+
+### Add `mdsvex`
+Adding other Svelte preprocessors works similar to how it would in any other Vite + Svelte project. 
+
+For example, let's refactor mdsvex's own docs example for [customizing extensions](https://mdsvex.pngwn.io/docs#extensions).
+
+To import markdown files as components, add `.md` to both the Svelte compiler and mdsvex extensions: 
+```js
+// cayo.config.js
+import { mdsvex } from "mdsvex";
+export default {
+  // Putting these options inside the svelte option object is the only difference
+  svelte: { 
+    extensions: ['.svelte', '.svx', '.md'],
+    preprocess: [
+      mdsvex({ extensions: ['.svx', '.md'] }),
+    ],
+  }
+}
+```
+
+---
+
+### Conditional Config
+Cayo doesn't have built-in features to support a conditional config. E.g., say you different config options for `cayo dev` and `cayo build`. 
+
+However, you can set up your dev environment to support this yourself. Here's an example that uses the `NODE_ENV` environment variable to swap configs when running `cayo`:
+
+**Define scripts that set the environment while running `cayo dev` and `cayo build`**
+
+`package.json`:
+```json
+"scripts": {
+  "dev": "export NODE_ENV=development && cayo dev",
+  "build": "export NODE_ENV=production && cayo build"
+}
+```
+
+**Add conditions in your Cayo config based on the value of NODE_ENV**
+
+`cayo.config.js`:
+```js
+let config;
+if (process.env.NODE_ENV === 'development') {
+  config = {
+    // development options for `cayo dev`
+  }
+} else if (process.env.NODE_ENV === 'production') {
+  config = {
+    // production options for `cayo build`
+  }
+}
+
+export default config;
+```
+
+Now when you run `npm run dev`:
+- `cayo dev` will run but also set `NODE_ENV` to `'development'`
+- the dev config will be used
+
+With this scripts setup, you could also use `process.env.NODE_ENV` in your components. Say you wanted to have a conditional [Template](../README.md#template-file):
+
+`__template.svelte`:
+```svelte
+{#if process.env.NODE_ENV === 'development'}
+  <div class="dev">
+    I'm running in development mode
+  </div>
+  %cayo.body%
+{:else}
+  %cayo.body%
+{/if}
+```

package/docs/how-cayo-works.md

@@ -0,0 +1,28 @@
+# How Cayo Works
+
+Some additional explanation of how things work within Cayo. This isn't need-to-know info in order to use Cayo, but if you're curious...
+
+## Render Hook
+
+The generated hook function looks something like this in `cayo-runtime.js` files:
+```js
+// cayo-runtime.js
+export default renderCayos(cb) {
+  var target = cb ? cb : (node) => node;
+  let cayos = {};
+  // Code that adds cayo instances to the `cayos` object
+  // Example, based on counter.cayo.svelte from earlier
+  // 'counter-f00b4r' is a generated unique identifier for the instance
+  cayos['counter-f00b4r'] = {};
+  cayos['counter-f00b4r'].target = document.querySelector('[data-cayo-id="counter-f00b4r"]');
+  cayos['counter-f00b4r'].instance = new ${componentName}({
+    target: target(cayos['counter-f00b4r'].target),
+    hydrate: true,
+    props: getProps(cayos['counter-f00b4r'].target),
+  });
+
+  return cayos;
+}
+```
+
+**Note:** `getProps()` is also generated in `cayo-runtime.js`. It handles parsing the props as a string, to use the props to hydrate the Cayo instance.

package/docs/why-i-created-cayo.md

@@ -0,0 +1,21 @@
+## Why I Created Cayo
+
+With so many other great tools out there, it does seem kind of silly to create a new, pretty niche tool with less features. It really came down to me having limitations to how I can build web pages on the particular web platform we use at work. Most of the pages I work with are content pages, with no need for any data flow to a database, and in general have small bits of interactivity (carousels, modals, etc). The "big stuff" is handled all within the source code of the web platform's framework. I don't have access to that source code, but I do have access to a CMS that essentially lets me upload HTML snippets them as a static page, or as a static _part_ of page. I call that the "little stuff."
+
+Also, I love Svelte. I wanted to use Svelte to write those HTML snippets. Since Svelte really is a compiler at heart, it seemed like the perfect fit. I realized I could use the Svelte API to server side render (SSR) them to HTML strings in any node environment, like in a CLI.
+
+Another requirement was: little-to-no-JS. For most of the content I build to then be imported into the CMS, it's completely static. Occasionally I need some JS to make a carousel do its thing. But, my JS can only be imported via a `<script>` within my HTML snippet—that means my JS gets loaded last, after anything already being loaded by the web platform in the <head>. Ultimately, I've gotta be careful about when/what JS is running in my HTML snippets, as their JS always gets delayed. 
+
+That's where Cayo Components come in. I wanted to be able to give the power of Svelte to those limited cases where I do need interactivity (JS). For the "islands of reactivity", or _cayos_, instead of SSR-ing these components, I bundle them up as JS for client side rendering (CSR). CSR components just require the Svelte vendor code to run, which is pretty small. And the output bundle is typically pretty small (but does scales with the complexity of the component itself), so I wasn't too worried about the overhead to have Svelte components run client side.
+
+### Okay, but can't SvelteKit and Astro do all of those things?
+
+Mostly, yes! And that's why Cayo is not recommended for most projects; those other frameworks are great for most people. 
+
+SvelteKit does have an adapter that is for using it as a "static site generator" (SSG), but I found that it still doesn't quite get you to a zero-JS output. Because SvelteKit is much more than an SSG, it isn't tailored to be one, so your output still includes some JS files and a hydration script on your page, even if you don't have _any_ JS for that page to make use of all that overhead/setup. For most people, that doesn't really matter! For my use case, I'd need to run scripts to comb through all that unnecessary overhead and remove it from the markup. That's much easier than creating an entirely new tool, but since SvelteKit is still in beta at the time of writing Cayo, I didn't want to find myself wrestling with SvelteKit as it's in flux.
+
+SvelteKit also doesn't support partial hydration within a page. It does however support prerendering page A, and hyrdrating page B, but that's not quite the same as island architecture.
+
+Astro, however, does check nearly every box for me. It supports island architecture (and their Astro Components have more features than Cayo Components). Their output doesn't include all the extra that SvelteKit includes when it doesn't need it. _At the time I set out to create Cayo_, the only thing missing for me was Vite—I wanted to be able to make use of Vite's plugin ecosystem. Now, it does use Vite. (So, go use Astro.)
+
+I studied Svelte, SvelteKit, and Astro docs and source code for hours throughout building Cayo; it really wouldn't exist without being inspired by those teams and ingenuity behind those projects.

package/lib/cli/build.js

@@ -0,0 +1,34 @@
+import path from 'path';
+import { build as viteBuild } from 'vite';
+
+export async function build(_cayo) {
+  const { config } = _cayo;
+  const root = config.cayoPath;
+  const inputs = {};
+  for (const [, page] of _cayo.pages) {
+    let key = page.url;
+    let source = `./${page.url}/index.html`
+    if (page.url === '/') {
+      key = 'index';
+      source = './index.html'
+    }
+    
+    inputs[key] = path.resolve(root, source);
+  }
+  
+  return await viteBuild({
+    root: config.cayoPath,
+    base: config.base,
+    publicDir: config.publicDir,
+    build: {
+      ...config.build,
+      emptyOutDir: true,
+      rollupOptions: {
+        ...config.vite.rollupOptions,
+        input: {
+          ...inputs,
+        },
+      }
+    }
+  })
+}

package/lib/cli/cli.js

@@ -0,0 +1,152 @@
+import yargs from 'yargs-parser';
+import fs from 'fs-extra';
+import chalk from 'chalk';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+import { 
+  writePageFiles,
+  cleanCayoPath,
+} from '#core/files.js';
+
+import { loadConfig } from '#core/config.js';
+import * as compile from '#core/compile/index.js';
+import logger from '#core/logger.js';
+import { debugStats } from '#core/utils.js';
+
+import { dev } from './dev.js';
+import { build } from './build.js';
+
+// / Handle arguments
+function resolveArgs(argv) {
+  const cmd = argv._[2];
+
+  const options = {
+    projectRoot: typeof argv.projectRoot === 'string' ? argv.projectRoot : undefined,
+    configPath: typeof argv.config === 'string' ? argv.config : undefined,
+    mode: cmd === 'build' ? 'production' : 'development',
+  }
+
+  switch (cmd) {
+    case 'build':
+    case 'dev':
+    case 'help':
+      return { cmd: cmd, options };
+    default:
+      return { cmd: 'unknown', options };
+  }
+}
+
+// Run
+export async function cli(args) {
+  const argv = yargs(args);
+  const command = resolveArgs(argv);
+  run(command);
+}
+
+const commands = new Map([
+  ['build', async (_cayo) => {
+    build(_cayo);
+    // await prerenderPages(config).then((pages)=> {
+    //   build(config, pages);
+    // });
+  }],
+  ['dev', (_cayo) => {
+    dev(_cayo);
+    // prerenderPages(config);
+    // watch(config);
+    // serve(config);
+  }], 
+  ['help', (_cayo) => {
+    help(_cayo, logger);
+  }], 
+  ['unknown', (_cayo) => {
+    help(_cayo, logger, true);
+  }], 
+]);
+
+function help(_cayo, logger, isUnknownCommand)  {
+  // TODO: help info
+  if (isUnknownCommand) console.log(`unknown command. here's some help:`)
+  console.log('help');
+}
+
+async function run(command) {
+  const { cmd, options } = command;
+  logger.log.info(
+    `\n  ${chalk.magenta.bold(`cayo.${cmd}`)}${chalk.dim(` starting`)}`, 
+    { timestamp: false }
+  );
+
+  // Initialize Cayo Config
+  let cayoConfig;
+  try {
+    cayoConfig = await loadConfig(options);
+  } catch (err) {
+    logger.error(err);
+    process.exit(1);
+  }
+
+  try {
+    const __VERSION__ = (await fs.readJSON(path.resolve(__dirname, '../../package.json'))).version;
+    // Initialize Cayo CLI runtime data
+    const _cayo = {
+      template: null,
+      pages: new Map(), 
+      components: new Map(),
+      stats: {
+        dependencies: { 
+          pages: {},
+          components: {},
+          entries: {},
+          assets: {},
+        },
+        cayoComponents: { },
+        compiled: {
+          paths: new Set(),
+        },
+      },
+      config: cayoConfig,
+      logger,
+      __VERSION__,
+    }
+
+    // Create a fresh cayo folder for this run
+    cleanCayoPath(_cayo.config.cayoPath);
+    
+    // Compile & Render all user page and their dependent component files
+    try {
+      // Compile template that will be used by all pages
+      await compile.template(_cayo);
+
+      await compile.pages(null, _cayo);
+      for (const [key, page] of _cayo.pages) {
+        page.dependencies = _cayo.stats.dependencies.pages[key];  
+        await page.render(_cayo, { load: true });
+      }
+
+      for (const [, page] of _cayo.pages) {
+        await writePageFiles(page, _cayo);
+      } 
+
+    } catch (err) {
+      logger.error(err);
+      if (cmd === 'build') {
+        process.exit(1);
+      }
+    }
+
+    // for debugging
+    if (_cayo.config.debug) {
+      debugStats(_cayo);
+    }
+    
+    // Run the command
+    commands.get(cmd)(_cayo);
+
+  } catch (err) {
+    logger.error(err);
+    process.exit(1);
+  }
+}

package/lib/cli/dev.js

@@ -0,0 +1,12 @@
+import { serve } from './serve.js';
+import { watch } from './watch.js';
+
+export function dev(_cayo) {
+  // for (const [,page] of _cayo.pages) {
+  //   page.render(true, _cayo.stats.cayoComponents).then(() => 
+  //     writePageFiles(page, config.cayoPath, config)
+  //   );
+  // }
+  watch(_cayo);
+  serve(_cayo.config);
+}

package/lib/cli/serve.js

@@ -0,0 +1,25 @@
+import { createServer } from 'vite';
+import merge from 'deepmerge';
+
+export async function serve(config) {
+
+  const serveConfig = {
+    root: config.cayoPath, 
+    publicDir: config.publicDir,
+    mode: config.mode,
+    base: config.base,
+    configFile: false,
+  }
+  
+  const server = await createServer({
+    ...merge(config.vite, serveConfig),
+  });
+
+  await server.listen();
+  server.printUrls();
+
+  // logger.log.info(
+  //   chalk.green('Server running at') + chalk.dim(`${page.name}`), 
+  //   { timestamp: true }
+  // );
+}