Reference sections
Reference › App modules
When working on larger projects, you might end up with pages at varying levels within the site, all of which need to use the same global resource (for example, a layout template or a utility class).
In these situations, your import statements might start to get unruly.
Take the following example:
my-site
├ site.layout.js
╰ books
╰ the-handmaids-tail
╰ pages
╰ cover.page.js
Let’s say your cover.page.js uses the site layout template.
Here’s what its import statement would look like:
import site from '../../../site.layout.js'
export default () => kitten.html`
<${site}>
…
</>
`
That’s both cumbersome to write and error-prone. (Especially when you consider that different pages at different levels of the hierarchy may want to use the same file. You don’t want to spend your day counting dots.)
Enter App Modules.
App Modules are special local Node modules that exist only in your app (not on npm). They live in the special app_modules folder in your project and Kitten knows to ignore them when calculating its routes from the file structure of your project.
App Modules, like all Node modules, need a package.json file but they can get away with specifying a subset of the information contained in ones for npm packages. And, like all Node modules, they need to be npm installed into your project (but from a local file path instead of from npmjs.org).
Finally, if you have type checking enabled in your projects, you should add an index.d.ts file to your App Modules so your editor doesn’t complain when using the TypeScript Language Server (LSP).
Here’s how you’d make your site layout into an App Module:
Create the app_modules directory and then a directory for your module:
mkdir -p app_modules/site-layoutAdd the files your module will need:
my-site ├ app_modules │ ╰ site-layout │ ├ site.layout.js │ ├ index.d.ts │ ╰ package.json ╰ books ╰ the-handmaids-tail ╰ pages ╰ cover.page.jsIn your package.json file, you need to specify three properties:
name,type, andmain:{ "name": "@app/site-layout", "type": "module", "main": "site.layout.js" }Finally, if you have type checking enabled and you want to avoid type errors in your editor, your index.d.ts file should look like this:
import siteLayout from './site.layout.js' export default siteLayout
And that’s it.
All you need to do then is to install the App Module.
From the root of your project, install your module using its local path:
npm install ./app_modules/site-layout
Finally, from cover.page.js (and any other page, anywhere in your project) you can now import your layout using:
import site from '@app/site-layout'
That’s much better, isn’t it?
Database app modules are a special type of app module that Kitten expects to have the name database.
You are not limited to using the default, untyped database Kitten sets up for you.
The default database, like many of the beautiful defaults in Kitten, exists to make it easy to get started with Kitten and use it to build quick Small Web places, teaching programming, etc.
If, however, you’re designing a Small Web place that you will need to maintain for a long period of time and/or that you are going to collaborate with others on, it would make sense to create your own database and to make it type safe so you get both errors and code completion during development time.
You can create your own custom database using a special type of app module called the database app module.
Like any other app module, your database app module goes in the special app_modules directory in the root of your project. What’s special is that the app module must be called database.
Make sure your database app modules are using JSDB version 6.0.1 or later as previous versions suffer from a possible data corruption/security issue where string keys were not being sanitised in the same way values were during serialisation.
To learn how to create your own database app module for your Small Web project, please read the Database App Module tutorial.
For a real world example, see the database app module in Catalyst that wraps Kitten’s global JSDB instance with type information and some utility methods.