Tooling

This document contains resources to help you in both the tooling and development of the svelte-native-forms project.

Two Projects in One

This project is a bit unusual in that it represents "two projects in one"!

The outer project (this one) serves two purposes: a: the interactive demo app and b: the formal documentation (both of which are published on GitHub Pages).

The tooling for this project is documented here and is seeded from sveltejs/template (the project template for Svelte apps).
The inner project (found in the snf/ directory) is the utility library (published on npm).

The tooling for this project is documented in the inner TOOLING.md and is seeded from sveltejs/component-template (the base for building shareable Svelte components).

The reason for this "two projects in one" approach is: first the integration aspect (obviously), but more importantly to take advantage of the boiler plate tooling templates (pretty much unmodified)!

At a Glance

NPM Scripts
Dependencies
Project Resources
Project Setup
Deploy Project
Setup New Feature Branch

NPM Scripts

This section provides a summary of the available NPM Scripts (organized by task):

DEVELOPMENT
===========
APP:
app:devServe ... launch dev server, with continuous build (watching for code changes)
                 http://localhost:5000/

DOCS:
docs:build   ... AI: ?? manually build the docs (into the _book/ dir)
                 1. start an internal web server pointing to _book/ dir
                 2. manually re-execute docs:build whenever docs/ change


APP
===
app:devServe ... launch dev server, with continuous build (watching for code changes)
                 http://localhost:5000/

                 INTERNAL SCRIPT:
devServe ....... launch dev server, with continuous build (watching for code changes)
                 http://localhost:5000/
                 NOTE: the internals of this script:
                       1. invokes the rollup bundler in a "watch" state (to: public/build)
                       2. implicitly invokes "npm start" to launch the server

                 INTERNAL SCRIPT:
devSyncDemoCode. auto-sync public/demoCode/ during development (i.e. **watch**)
                 
                 INTERNAL SCRIPT:
start .......... start a static file server from the contents of public/
                 http://localhost:5000/
                 NOTE: This is implicitly invoked from devServe script
                       As a result, it CANNOT be renamed :-(
                 NOTE: You can invoke this explicitly to server the contents of
                       a production build (i.e. app:prodBuild)

app:deploy ..... deploy latest application to https://svelte-native-forms.js.org/app/
                 NOTE: This script FIRST builds the app from scratch
                       ... via preapp:deploy

app:prodBuild .. build production bundle (to: public/build)
                 NOTE: This is implicitly invoked from app:deploy

app:clean ...... AI: ?? clean the machine-generated public/build directory


DOCS
====
docs:build   ... AI: ?? manually build the docs (into the _book/ dir)
                 - NOTE: this build is executed as the first step in docs:publish
                 - FOR DOCS DEVELOPMENT:
                   1. start an internal web server pointing to _book/ dir
                   2. manually re-execute docs:build whenever docs/ change
                 - this is MUCH PREFERRED over docs:serve
                   * it is MUCH FASTER!
                   * docs:serve is very antiquated (a dead project)
                     * it is extremely slow
                     * it constantly stops when any file changes
                                    
docs:publish ... AI: ?? publish the latest docs to https://svelte-native-forms.js.org/docs/
                 NOTE: this script FIRST builds the docs from scratch
                       ... via predocs:publish

docs:clean   ... AI: ?? clean machine-generated docs/ directory

                 >>> ANTIQUATED (see notes on docs:build)
docs:serve ..... launch docs server, continuously watching for docs changes
                 NOTE: adding `--log=debug --debug` to this npm script CAN BE USEFUL


MISC
====
clean .......... AI: ?? cleans ALL machine-generated directories

Dependencies

This section provides some insight regarding the various dependencies found in svelte-native-forms.

The dependency list can become quite large for a mature project. In looking at package.json, the inevitable questions are:

What is this dependency
Why is it needed
Is it a dependency for project tooling or application code?

This last bullet is especially poignant because all Svelte project dependencies are devDependencies, due to the fact that all run-time resources are bundled together by the Svelte compiler.

The following table itemizes the svelte-native-forms dependencies, referencing when/where they were introduced/configured.

Dependency	Type	Usage	Refer To
`@rollup/plugin-alias`	TOOLING	Absolute Imports	Setup Absolute Imports
`@rollup/plugin-commonjs`	TOOLING	Svelte Bundler related	Setup Svelte App Tooling
`@rollup/plugin-node-resolve`	TOOLING	Svelte Bundler related	Setup Svelte App Tooling
`autoprefixer`	TOOLING	Tailwind CSS Build	Setup Tailwind CSS
`cpx`	TOOLING	Display Source Code	Setup Code Samples
`gh-pages`	TOOLING	Deployment	Setup Svelte App Tooling
`npm-run-all`	TOOLING	Display Source Code	Setup Code Samples
`rollup`	TOOLING	Svelte Bundler	Setup Svelte App Tooling
`rollup-plugin-css-only`	TOOLING	Svelte Bundler related	Setup Svelte App Tooling
`rollup-plugin-livereload`	TOOLING	Svelte Bundler related	Setup Svelte App Tooling
`rollup-plugin-svelte`	TOOLING	Svelte Bundler related	Setup Svelte App Tooling
`rollup-plugin-terser`	TOOLING	Svelte Bundler related	Setup Svelte App Tooling
`sirv-cli`	TOOLING	A static file server	Setup Svelte App Tooling
`svelte`	TOOLING	Svelte Compiler	Setup Svelte App Tooling
`svelte-highlight`	TOOLING APP	Display Source Code in application	Setup Code Samples and `src/util/ui/ShowCode.svelte`
`svelte-preprocess`	TOOLING	Tailwind CSS Build	Setup Tailwind CSS
`tailwindcss`	TOOLING APP	Tailwind CSS Build and application code	Setup Tailwind CSS and app code: `src/...`
`tw-themes`	TOOLING APP	Tailwind Themes and application code	Setup tw-themes and app code: `src/...`

Project Resources

Wondering what some of the top-level file resources are? Here is a summary:

svelte-native-forms/
  .git/ ................ our local git repo
  .gitignore ........... git repo exclusions (typically machine generated)
  LICENSE.md ........... our MIT License
  node_modules/ ........ install location of dependent packages (maintained by npm)
  package.json ......... project meta data with dependencies
  package-lock.json .... exhaustive dependency list with installed "locked" versions (maintained by npm)
  public/ .............. the app deployment root (with generated build/) see: "Setup Svelte App Tooling"
  README.md ............ basic project docs
  rollup.config.js ..... the rollup bundler configuration (used by Svelte) see: "Setup Svelte App Tooling"
  snf/ ................. the inner project, hosting our util lib published on npm see: snf/TOOLING.md
  src/ ................. the app source code
    main.js ............ mainline entry point (redirect to Main.svelte)
    Main.svelte ........ general place to do setup/config (including Tailwind)
    App.svelte ......... our top-most App component (launched from Main.svelte)
    snip snip .......... many more!
  tailwind.config.js ... the tailwind css configuration file
  TOOLING.md ........... this document :-)

  ?? L8TR: (as needed)
  _book/ ............... machine generated docs (output of GitBook) see: "Setup Docs Tooling"
  docs/ ................ master source of GitBook project docs  see: "Setup Docs Tooling"
    *.md ............... various Markdown files making up our docs

Project Setup

This section chronicles the original setup of the svelte-native-forms project.

If you are forking this project, this detail is unnecessary, because you simply npm install and then commence your development.

With that said, this section provides valuable insight on how the project was originally setup and configured, and can be used in other projects (where you are starting from scratch)!

NOTE: These sections roughly represent the chronology of when they were carried out, however in some cases the order can be changed.

Sub Sections:

Setup GitHub Project
Setup Svelte App Tooling
Setup Tailwind CSS
Setup tw-themes
Setup Absolute Imports
Setup Code Samples
Setup Docs Tooling
Setup js.org sub-domain

Setup GitHub Project

There are many ways of initiating a new GitHub project. I'll leave the details to you :-)

At the end of this process you should have:

A new GitHub project
A local git repository (for your development)

Impacted Files:

  svelte-native-forms/
    .git/ ................ our local git repo
    .gitignore ........... git repo exclusions (typically machine generated)
    README.md ............ basic project docs

My personal notes are "hidden" (in comment form) in this doc ...

Setup Svelte App Tooling

svelte-native-forms uses a Svelte App for it's Demo App.

This setup assumes you are "starting from scratch", setting up the Svelte tooling (the compiler, etc.), with the basic application code template.

At the end of this process you should have:

A running Svelte app (a very basic template starting point)
The ability to deploy the demo app (to github pages)
```
$ npm run app:deploy
```
The svelte-native-forms demo app is deployed on GitHub Pages (along with the documentation).

Impacted Dependencies:

@rollup/plugin-commonjs
@rollup/plugin-node-resolve
gh-pages
rollup
rollup-plugin-css-only
rollup-plugin-livereload
rollup-plugin-svelte
rollup-plugin-terser
sirv-cli
svelte

Impacted Files:

svelte-native-forms/
  node_modules/ ........ install location of dependent packages (maintained by npm)
  package.json ......... project meta data with dependencies
  package-lock.json .... exhaustive dependency list with installed "locked" versions (maintained by npm)
  public/ .............. the Svelte app deployment root (with generated build/) [see: "Setup Svelte App Tooling"]
  rollup.config.js ..... the rollup bundler configuration (used by Svelte) [see: "Setup Svelte App Tooling"]
  src/ ................. the app source code (the basic template starting point)

Install Template:

Make a copy of the Svelte Template Repo using degit (a Rich Harris tool that copies git repositories)

Original Instructions:

Getting started with Svelte (from the Svelte site - the horses mouth)
Getting Started with Svelte 3 (pretty much same instructions)
Svelte Template Repo

- Summary Instructions:
  $ cd c:/dev
  $ npx degit sveltejs/template svelte-native-forms
  $ cd svelte-native-forms
  $ npm install
  $ npm run dev

  * Update package.json with any additional fields you may desire
    (description, homepage, repository, keywords, license, etc.)

  * Move sirv-cli FROM: dependencies TO: devDependencies (in package.json)
    ... unsure why template registers this as dependencies

- Summary of npm scripts:

                     >>> renamed FROM: dev
  * app:devServe ... launch dev server, with continuous build (watching for code changes)
                     http://localhost:5000/
                     NOTE: the internals of this script:
                           1. invokes the rollup bundler in a "watch" state (to: public/build)
                           2. implicitly invokes "npm start" to launch the server

  * start .......... start a static file server from the contents of public/
                     http://localhost:5000/
                     NOTE: This is implicitly invoked from app:devServe script
                           As a result, it CANNOT be renamed :-(
                     NOTE: You can invoke this explicitly to server the contents of
                           a production build (i.e. app:prodBuild)

  * app:deploy ..... deploy latest application to https://svelte-native-forms.js.org/app/
                     NOTE: This script FIRST builds the app from scratch
                           ... via preapp:deploy

                     >>> renamed FROM: build
  * app:prodBuild .. build production bundle (to: public/build)
                     NOTE: This is implicitly invoked from app:deploy

  * app:clean ...... AI: ?? clean the machine-generated public/build directory

Install gh-pages:

NOTE: Some of these dependencies overlap with other setup (Install only what is missing):

All deployment scripts use the gh-pages utility, that simplifies publishing resources to GitHub Pages. Install as follows:

$ npm install --save-dev gh-pages

Relative App Resources

Because our app is deployed to a sub-directory of github pages, all startup html resource references should be relative. Simply change public/index.html as follows:

public/index.html
=================
-   <link rel='icon' type='/image/png' href='/favicon.png'>
+   <link rel='icon' type='/image/png' href='favicon.png'>

-   <link rel='stylesheet' href='/global.css'>
+   <link rel='stylesheet' href='global.css'>

-   <link rel='stylesheet' href='/build/bundle.css'>
+   <link rel='stylesheet' href='build/bundle.css'>

-   <script defer src='/build/bundle.js'></script>
+   <script defer src='build/bundle.js'></script>

Add app:deploy Script

Add the following scripts to package.json:

package.json
============
{
  ...
  "scripts": {
    "preapp:deploy": "npm run app:prodBuild",
    "app:deploy": "gh-pages --dist public --dest app",
    ... snip snip
  }  
}

My personal Detailed Notes are "hidden" (in comment form) in this doc ...

Setup Tailwind CSS

The svelte-native-forms demo app styles it's components based on Tailwind CSS.

This utility requires a build process that:

Enables tailwind in general (the @tailwind directives found in src/Main.svelte).
Enable tailwind advanced directives (@apply, @layer, etc.).
Purging unneeded styles (for production builds). The number of tailwind css classes are massive (over 1.5 meg). A "production" build can prune this large resource to only what is used by a given application. This is employed for "production" builds only, because it would be too time consuming to apply this for every development change.

Enabling and configuring the tailwind-portion of the build can be a bit confusing, due to the large number of frameworks. These instructions are specific to Svelte.

At the end of this process you should have:

Tailwind CSS fully integrated in our Svelte app

Impacted Dependencies:

svelte-preprocess - A Svelte preprocessor with sensible defaults and support for: 
                    PostCSS, SCSS, Less, Stylus, CoffeeScript, TypeScript, Pug and much more.
                    ... Svelte's own parser understands only JavaScript, CSS and its HTML-like
                        syntax. To make it possible to write components in other languages,
                        such as TypeScript or SCSS, Svelte provides the preprocess API, which
                        allows to easily transform the content of your markup and your
                        style/script tags.

tailwindcss       - A PostCSS plugin for tailwind
                    ... A utility-first CSS framework for rapidly building custom user interfaces.
                    ... this is what we are here for

autoprefixer      - A PostCSS plugin to parse CSS and add vendor prefixes to CSS rules using values
                    from "Can I Use"
                    ... like: -webkit- (Chrome, Android, iOS, Safari),
                              -moz- (FireFox),
                              -ms- (IE),
                              -o- (Opera)

NOT CURRENTLY INSTALLED/USED: ---------------------------------------------------------------

postcss-nesting   - A PostCSS Nesting plugin, letting you nest style rules inside each other, 
                    following the CSS Nesting specification. ... KJB: hmmmm
                      /* THIS: */
                      a, b {
                        color: red;
                       
                        & c, & d {
                          color: white;
                        }
                      }
                      /* BECOMES: */
                      a, b {
                        color: red;
                      }
                      a c, a d, b c, b d {
                        color: white;
                      }

@tailwindcss/ui   - OPTIONAL tailwind ui plugin <<< NO README ... 50K downloads / week
                    * KJB: I think this is a package of tailwind defs for pre-packaged components
                           MAY BE a PURCHASED PRODUCT (found a site for that)
                           ... https://tailwindui.com/

Impacted Files:

svelte-native-forms/
  tailwind.config.js ... the tailwind configuration file
  rollup.config.js ..... modified in support of tailwind
  src/
    main.js ............ mainline entry point (redirect to Main.svelte)
    Main.svelte ........ general place to do setup/config (including Tailwind)
    App.svelte ......... our top-most App component (launched from Main.svelte)

Instructions:

Official Install Docs ... not svelte specific
How to Set Up Svelte with Tailwind CSS ... what I followed
Svelte & Tailwind Css, minimal install ... hmmm

Installation Summary:

NOTE: Tailwind build process requires Node.js 12.13.0 or higher.

install dependencies:

$ npm install --save-dev svelte-preprocess tailwindcss autoprefixer
  + autoprefixer@10.2.4
  + tailwindcss@2.0.3
  + svelte-preprocess@4.6.9

add tailwind.config.js at root:

tailwind.config.js
==================
                                              // KJB: same as in rollup.config.js
const production = !process.env.ROLLUP_WATCH; // or some other env var like NODE_ENV
export default {
  future: { // for tailwind 2.0 compatibility
    purgeLayersByDefault: true, 
    removeDeprecatedGapUtilities: true,
  },
  plugins: [
    // for tailwind UI users only
    // require('@tailwindcss/ui'), KJB: not using @tailwindcss/ui (can't find info on this)
    // other plugins here
  ],
  purge: {
    content: [
      "./src/**/*.svelte",
      // may also want to include base index.html
    ], 
    enabled: production // disable purge in dev
  },
};

setup rollup.config.js WITH svelte-preprocess MANAGING tailwindcss and autoprefixer

rollup.config.js
================
  ...
+ import sveltePreprocess from 'svelte-preprocess'; // KJB: supporting tailwindCSS
  ...
  plugins: [
    svelte({
      ...
+     // KJB: supporting tailwindCSS
+     preprocess: sveltePreprocess({
+       // https://github.com/kaisermann/svelte-preprocess/#user-content-options
+       sourceMap: !production,
+       postcss: {
+         plugins: [
+           require("tailwindcss"), 
+           require("autoprefixer"),
+         //require("postcss-nesting"),
+         ],
+       },
+     }),
      ...
    }),
  ],
  ...

configure Tailwind in our Svelte App

src/main.js <<< have it direct to Main.svelte
===========
import Main from './Main.svelte';

const main = new Main({
  target: document.body,
});

export default main;

src/Main.svelte <<< general place to do setup/config (including Tailwind)
===============
<script>
 import App from './App.svelte'
</script>

<!-- launch our App -->
<App/>

<!-- setup Tailwind CSS (NOTE: do NOT believe lang="postcss" is needed) -->
<style global lang="postcss">

 /* only apply purgecss on utilities, per Tailwind docs */
 /* purgecss start ignore */
 @tailwind base;
 @tailwind components;
 /* purgecss end ignore */

 @tailwind utilities;
</style>

src/App.js <<< our top-level App component
==========
app specific (whatever is needed for our app)

Disable the global.css (from the svelte template) so as to NOT interfere with tailwind css. Simply remove it from index.html.
```
public/index.html
=================
- <link rel='stylesheet' href='global.css'>
```

TEST:

<p class="bg-red-500">Styled with tailwind ... should be red!</p>

NOTE: when changing Main.svelte the build is slow (upwards of 20 sec) ... because of the processing of the @tailwind directives. This overhead is also incurred at the build startup. Fortunately, this file rarely changes.
NOTE: A prior rendition of these instructions involved additional npm scripts to run postcss-cli, but Chris Dhanaraj realized that this was NOT needed, since Svelte already had a way to inject CSS and svelte-preprocess that runs on every Svelte file.
UNRESOLVED: FOR PURGING: Svelte has a class: binding syntax that isn't supported by Tailwind out of the box. There is an open discussion for this.
- Open Discussion Currently Tailwind’s default purge doesn’t match Svelte’s class: directive.
  SO: bg-red-500 will be removed in prod:

My personal Detailed Notes are "hidden" (in comment form) in this doc ...

Setup tw-themes

Our application color themes are provided through tw-themes.

At the end of this process you should have:

Application access to the TwThemes object (where color themes can be activated)
Impacted Dependencies:
```
tw-themes
```

Impacted Files:

svelte-native-forms/
  rollup.config.js
  tailwind.config.js

Original Instructions:

tw-themes (see Install and Getting Started sections)

Summary:

Install Dependencies:

$ npm install --save-dev tw-themes
  + tw-themes@0.1.1

The key aspect is we create an application module (see src/layout/colorTheme.js) that promotes the TwThemes object, from which the remainder of the API is gleaned.

From a tooling perspective, we must inform tailwind of our Context Colors, by referencing this TwThemes object in tailwind.config.js, through the following snippet:

tailwind.config.js
==================
import TwThemes from './src/layout/colorTheme';

export default {

  ... snip snip

  // define our abstract Context Colors
  theme: {
    extend: {
      colors: TwThemes.colorConfig(),
    },
  },

  ... snip snip
};

ISSUE:

There is an issue here in that we are importing application code in this configuration file, which means it must support ES Modules.

Currently, tailwind does NOT support ES Modules in it's configuration file.

FIX:

To work around this, our rollup.config.js resolves this configuration file, and passes it directly to the tailwindcss plugin function:

rollup.config.js
================
import tailwindcss    from 'tailwindcss';          // NEW: in support of ES Modules
import tailwindConfig from './tailwind.config.js'; //      (found in tailwind.config.js)
... snip snip
export default {
  ... snip snip
  plugins: [
    svelte({
      ... snip snip
      preprocess: sveltePreprocess({
        ... snip snip
        postcss: {
          plugins: [
            ... snip snip
         // require("tailwindcss"),      // ... NEW: normal usage
            tailwindcss(tailwindConfig), // ... NEW: in support of ES Modules (in tailwind.config.js)

Setup Absolute Imports

We setup a 'svelte-native-forms' absolute import to make it appear that our demo code is importing the installed package, even though it is aliased to this code base.

NOTE: There is a know bug in the alias rollup plugin, detailed here and here. This bug is only relevant when you use a mix of both absolute and relative imports on a module that maintains state. When this happens there are two modules, and their state is duplicated :-( Currently, we restrict the usage of absolute imports to the simulated 'svelte-native-forms' package. Please be aware of this known bug, should you choose to expand the usage of absolute imports.

To alleviate the pain of relative path imports (for example):

import TreeView  from "../../../../util/comp/TreeView.svelte";

We enable absolute imports, where tilde (~/) is the src root (src/):

import TreeView  from "~/util/comp/TreeView.svelte";

Notes:

When using defined aliases, you must supply the extensions (.js, .svelte, etc.)
You cannot prefix with src/ out of the box (without this alias utility).
Currently our unit tests may not import any code that uses alias imports ... because jest does NOT utilize rollup
You can define as many aliases as you like
You can even employ regexp (see alias docs for details)

Links:

Absolute Paths in Svelte
npm: @rollup/plugin-alias

At the end of this process you should have:

The ability to utilize absolute imports.
Impacted Dependencies:
```
@rollup/plugin-alias
```

Impacted Files:

svelte-native-forms/
  rollup.config.js ... modified to include alias configuration (Absolute Imports)

Installation Details:

Install required dependencies (@rollup/plugin-alias):

$ npm install --save-dev @rollup/plugin-alias
  + @rollup/plugin-alias@3.1.2
    added 2 packages from 2 contributors and audited 206 packages in 1.963s

Configure rollup.config.js (in support of Absolute Imports)

For details, see embedded comments (Absolute Imports) in rollup.config.js

rollup.config.js sample

import alias from '@rollup/plugin-alias';  // KJB: in support of: Absolute Imports

export default {
  ...
  plugins: [
    ...
    // KJB: Absolute Imports
    alias({
      entries: [
        // allow:      import {formChecker}  from "svelte-native-forms";
        // instead of: import {formChecker}  from "../../snf/src";
        { find: 'svelte-native-forms', replacement: 'snf/src/index.js' },
      ]
    })
  ]
};

Setup Code Samples

The svelte-native-forms demo app can display the source code for each demo. This is accomplished by staging the demo source to a run-time resource (FROM: src/demo/ TO: public/demoCode/) and retrieving it at run-time for display. The display is accomplished through our internal <ShowCode> component, which employs the svelte-highlight npm component library, which in turn is layered on top of the highlight.js package.

Requirements:

auto-sync of public/demoCode/ during development (i.e. watch)
syntax highlight of code
link to code in github -and/or- copy paste
AI: yellow-highlighter of selected code snippets (punted on this one for now)

Syntax Highlighters Research:

svelte-highlight (what we are using - "path of least resistance")
highlight.js (used by svelte-highlight)
Prism (very popular, but took the "path of least resistance")

At the end of this process you will have:

The ability to display the source code for each demo
Impacted Dependencies:
```
svelte-highlight
npm-run-all
cpx
```

Impacted Files:

svelte-native-forms/
  .gitignore
  package.json

Install Summary:

Install Dependencies:

$ npm install --save-dev svelte-highlight
  + svelte-highlight@0.7.1
    added 8 packages from 314 contributors and audited 214 packages in 4.923s
$ npm install --save-dev npm-run-all
  + npm-run-all@4.1.5
    added 53 packages from 33 contributors and audited 457 packages in 6.339s
$ npm install --save-dev cpx
  + cpx@1.5.0
    added 189 packages from 114 contributors and audited 404 packages in 9.751s

Modify the NPM Scripts in package.json as follows:

package.json
============
{
  ...
  "scripts": {
    "devServe": "rollup -c -w",
    "devSyncDemoCode": "cpx src/demo/**/*.svelte public/demoCode/ --clean --verbose --watch",
    "app:devServe": "npm-run-all --parallel devSyncDemoCode devServe",
    "preapp:prodBuild": "cpx src/demo/**/*.svelte public/demoCode/ --clean --verbose",
    ... snip snip
  }  
}

Add following to .gitignore:

.gitignore
==========
/public/demoCode/

Setup Docs Tooling

TODO: ?? details to follow

Setup js.org sub-domain

To accommodate a more professional URL, js.org supports a sub-domain registration process.

At the end of this process you should have:

A github pages js.org sub-domain:
- FROM: https://kevinast.github.io/svelte-native-forms/
- TO: https://svelte-native-forms.js.org/

To accomplish this, simply follow the instructions on js.org. Here is my summary (more notes hidden here in comment form):

First setup a preliminary set of docs that are deployable to GitHub Pages. js.org requires "reasonable content" before they will approve your request. Alternatively you can create some temporary content that shows your intent.
Create a CNAME file at gh-pages root. In our case the gh-pages root is the parent of both our published resources (docs and app). You want to publish a temporary resource directly in the gh-pages root.

tempLoc/CNAME
```
svelte-native-forms.js.org
```
- Deploy this temporary resource to the GitHub Pages root:
```
$ npx gh-pages --dist tempLoc
```
  NOTE: Once this is done, you will not be able to browse your gh-pages till js.org processes your PR (below).
Fork the js.org project and issue a PR to introduce our sub-domain
- new entry in:
  
  cnames_active.js
```
"svelte-native-forms": "kevinast.github.io/svelte-native-forms",
```
Monitor PR acceptance (will take 24 hrs).
Once complete the sub-domain should be active

Deploy Project

AI: ?? This may not yet be complete, but it is close (should include details of inner/outer projects)

This section chronicles the steps in deploying svelte-native-forms to NPM, and publishing the docs and demo app.

Feature Branch:

Typically all development is done in a feature branch. If you are about to deploy, presumably your branch is complete and documented.

finalize version -and- history notes:
- for the new version, use semantic standards
- update version in:
  - package.json (both inner and outer projects)
  - docs/toc.md (version is referenced at top)
  - docs/history.md (within the "running" notes)
- review/finalize all documentation impacted by change
  - also insure README.md does NOT need to change
    - NOTE: don't forget, the README is duplicated in the inner project (sync as necessary)!
- optionally: save a link-neutral version of change history comments (to use in git tagging)
  - pull from history.md (normalizing any reference links)
  - ALTERNATE: simply reference the documentation history section (in the git tag)
    
    EX: https://svelte-native-forms.js.org/history.html#v0_1_0

main Branch:

issue PR (pull request) and merge to main branch
sync main to local machine (where the deployment will occur)
verify version is correct in:
- package.json (both inner and outer projects)
- docs/toc.md
- docs/history.md
now, everything should be checked in to main and ready to publish
tag the release (in github)
- verify the history page github links are correct (now that the tag exists)
publish svelte-native-forms to npm (THIS IS IT!):
```
 $ cd snf/snf # go into inner project (where our library is)
 $ npm publish
   + svelte-native-forms@v.v.v
```
verify publish was successful
- receive email from npm
- npm package: https://www.npmjs.com/package/svelte-native-forms
- unpkg.com: https://unpkg.com/svelte-native-forms/
publish svelte-native-forms documentation:
```
$ npm run docs:publish
```
verify publish docs was successful
- https://svelte-native-forms.js.org/docs
  - see new version
  - see correct history
deploy svelte-native-forms demo app:
```
$ npm run app:deploy
```
verify deployed app was successful
- https://svelte-native-forms.js.org/app
  - see new version
optionally test the new package in an external project (by installing it)

Setup New Feature Branch

AI: ?? This may not yet be complete, but it is close (should include details of inner/outer projects)

This section documents the steps to setup a new feature branch (where all development is typically done):

create a new branch (typically spawned from the "main" branch).

EX: next7
devise "best guess" as to the next version number (may be premature, but this can subsequently change).

Reflect this in:
- package.json (both inner and outer projects)
- docs/toc.md (version is referenced at top)
- docs/history.md (within the "running" notes)
setup new running Revision History (in docs/history.md)

This provides a place where we can incrementally maintain "running" revision notes.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

TOOLING.md

TOOLING.md

Tooling

Two Projects in One

At a Glance

NPM Scripts

Dependencies

Project Resources

Project Setup

Setup GitHub Project

Setup Svelte App Tooling

Setup Tailwind CSS

Setup tw-themes

Setup Absolute Imports

Setup Code Samples

Setup Docs Tooling

Setup js.org sub-domain

Deploy Project

Setup New Feature Branch

Files

TOOLING.md

Latest commit

History

TOOLING.md

File metadata and controls

Tooling

Two Projects in One

At a Glance

NPM Scripts

Dependencies

Project Resources

Project Setup

Setup GitHub Project

Setup Svelte App Tooling

Setup Tailwind CSS

Setup tw-themes

Setup Absolute Imports

Setup Code Samples

Setup Docs Tooling

Setup js.org sub-domain

Deploy Project

Setup New Feature Branch