ns-front v0.3.0
ns-front
A meta-tool for creating, distributing and using exchangeable front end templates.
Why
Endless templates generate code quickly. But what happens when you want to update it? And wouldn't it be nice if you someone else would deal with the constant bot security complaints about packages in the code you've inherited?
The hard part of software development isn't usually building it, but rather maintaining it. Good software constantly evolves.
Today, software is made from endless packages evolving under our feet. This CLI was created to leverage external package maintenance with minimal refactoring. It's intended for both template developers and users.
What
ns-front (short for "No Stack Front") is CLI for front end templates that can be exchanged as easily as WordPress themes. You can create templates for yourself or others that have regions built in for customized code. Then users of the template can upgrade easily, or even exchange templates within a category, without losing their custom changes.
(By category we mean the 'type' of produced app. That is vague, and we may soon support more specific classifications, but in general a category should include a front end framework and probably a type of expected back end.)
Currently, a template must be stored in a repo and distributed separately, and must conform to required standards explained below.
#Features
- A
newapp
command to generate an "empty" placeholder app of the type used by a template. (The way thatcreate-react-app
creates a placeholder React app.) The template specifies how such a placeholder gets created, so if you like you can use ns-front to let others generate some unique type of application. - A command
makecode
that generates an app from a template. - A
test
command to be sure that no custom code that the template user created violates the standards for the template. The test ensures that custome code conforms to the NoStack Front End Guidelines. (Otherwise, you could lose your custom code when you update your template!) - A flexible, hierarchical approach: rather than limiting an app to standard pages (you know, a cookie cutter), a template relies upon a flexible specification with the units and hierarchies of components that you need in your app. Also, a template can (and should) allow for custom styling, so that any mockup can be used with a decent template.
- Easy to use: Simple handlebars with a simple standard structure for templates.
- Coming Soon A searchable list for registering templates, so that if you create a template others can find it.
- Templates that support the NoStack service also can be used with autogenerated backends, so that you can throw together and then modify your whole stack with minimal code.
History of the Project
We created this because we needed it at NoStack. Originally, we created a tool that was specific to our needs. But then we realized that it would support a lot more people if we made it more generic.
So, we turned it into a tool that supports any type of template. Unfortunately, there's a problem as of today that you need an extra file ("stack.json") that most people won't have (see issue 1). That's our top priority to remove today. But we have to release our current version, because we're still using it ourselves. So, if you want to use this right now, contact us about generating one for you (info at nostack dot net). Meanwhile, we're on it...
So far we've got one template, and we are pulling together the documentation.
If you want to help with this project, please open issues and start talking to us! Or just reach out to info at nostack dot net.
Usage
$ npm install -g ns-front
$ nsfront COMMAND
running command...
$ nsfront (-v|--version|version)
ns-front/1.0.0-0 linux-x64 node-v14.9.0
$ nsfront --help [COMMAND]
USAGE
$ nsfront COMMAND
...
Commands
nsfront help [COMMAND]
display help for nsfront
USAGE
$ nsfront help [COMMAND]
ARGUMENTS
COMMAND command to show help for
OPTIONS
--all see all commands in CLI
See code: @oclif/plugin-help
nsfront makecode
generates or updates code from a template, preserving custom changes. The app directory should have been prepared the first time with a call to newapp
USAGE
$ nsfront makecode
OPTIONS
-a, --appDir=appDir application directory
-h, --help show CLI help
EXAMPLE
$ nostack makecode -a ~/temp/myapp
See code: src/commands/makecode.ts
nsfront newapp
new placeholder app. Creates an "empty" app (like create-react-app) for a template that you can build on with makecode.
USAGE
$ nsfront newapp
OPTIONS
-a, --appDir=appDir application directory
-b, --baseApp=baseApp directory of the base app to copy. If it does not exist, it is created.
-h, --help show CLI help
-t, --templateDir=templateDir template directory
EXAMPLE
$ nostack newapp -t ~/templates/basicTemplate -a ~/temp/myapp -b ~/temp/baseapp
See code: src/commands/newapp.ts
nsfront test
Confirms that your code is not violating any of the rules for testing required by nostack. For documentation about those rules, please see https://bit.ly/nsFrontEndRules. This is actually one of the tests conducted by NoStack to gauge the quality of submitted code. Essentially, the test generates a new version of the code and then simply compares it against your current version. If there are differences, then there is a problem with your code.
USAGE
$ nsfront test
OPTIONS
-a, --appDir=appDir application directory
-h, --help show CLI help
EXAMPLE
$ nsfront test -a ~/temp/myApp
See code: src/commands/test.ts
#Using Templates
Follow these steps:
1. Clone the template to your local.
2. Call nsfront newapp -t <template dir> -a <placeholder app directory>
and the placeholder app will be created wherever you specified. This step may take some time (for instance, if the template has to install a lot of packages).
3. Copy your placeholder app to a new app directory (or just use the placeholder itself).
4. Open the app.yml
file in the "meta" directory. You need to replace myApp
with the name that you want, and if necessary globally replace user
with whatever you want for the user for that app, e.g. buyer
.
5. You need to create a set of units under units. The symantic meaning of a unit will vary depending upon the template, but you can roughly think of them as pages or screens in your app. Each one must have a hierarchy
of data types. See Creating a Data Type Hierarchy(##Creating a Data Type Hierarchy) below.
6. Call makecode
to generate your app code according to the template.
7. Add custom code in accordance with
You can update the template whenever you like. Just bear in mind the following wa
##Creating a Data Type Hierarchy
A Unit is a building block for an app user interface. It also can be a query to the back end. ns-front
expects a hierarchy of data types for each unit. So a 'unit' in ns-front
terms is a hierarchy of types where each type appears only once in that unit More complex interfaces can be built with joining units, which provides complete querying expressive power.
You can, of course, start simple and build them up. Any time you like, you can call makecode
and it will modify the code that you have so far to include changes to your units and their hierarchies.
To create a hierarchy, think in terms of what you want to display. If for instance you expect to show a list of watches as the highest level of a UI unit, then your hierarchy should be rooted in watches. Maybe for each watch you will have a list of sellers.
catalog:
hierarchy:
watch:
store:
location: null
hours: null
phone: null
cost: null
But if you want the sellers to be shown on the top with the watches that they carry, then you'd reverse that.
catalog:
hierarchy:
store:
location: null
hours: null
phone: null
watch
cost: null
You can extend a hierarchy as many levels deep as you like. When a type has no child types, it should receive the value of null.
Note that nothing is stated in the hierarchy about data type. Every type in a hierarchy can be a string, a number, a or a set. By default, everything is a string. When you want to generate a backend as well, you need to provide more information. But to start you can try producing something with just strings.
#Working with Test Results
The diff files in <appPath>.test/diffs
show a number of problems. If you understand what's happening, the solutions are usually straightforward, but it may seem confusing at first.
It helps to understand clearly that your code files in <appPath>/src/components
are being compared to generated versions in <appPath>.test/src/components
. You may want to learn the basics of diff
outputs if you haven't already.
The problems (and their likely causes and solutions) are shown below. They can be one of the following:
1. There are lines in the generated test code that do not appear in yours. That would indicate that you removed some code, or that something in the version of your ns-front is more uptodate than the version used to generate your code. The solution is to add those lines to your code in the line number indicated, and then to try the test again.
2. Your code has lines not in the generated code. That usually indicates that you added code in places not permitted in the code. You need to insert all of your custom code in ns-custom areas, or to replace a section of the generated code using the "replacement" delimiter. It's always preferred to place code into a custom area rather than replacing, but if you must then replacement works.
3. Your code is simply different. That situation can arise from one of two situations:
a. You may simply need to lint your code and remove linting errors. For instance, it could be that your code using a double quote and the generated code uses a single quote.
b. Your code may have missing or altered comment lines for delimiting sections or custom code areas. You may have to look at the generated code a bit to identify the discrepancies.
4. Your code has files that don't appear in the generated code. You need to move them to the src/custom
directory.
5. The generated code has files that don't appear in your code. That normally means that you deleted a generated file. Technically, that doesn't pose an immediate problem, given that in the worst case a future regeneration of code will add a file. But the deletion won't last. Probably there's a better solution by replacement of sections, possibly incorporating code or components programmed within the src/custom
directory.
Creating Templates
To create templates, you have to know the basics of handlebars. (It's a very simple language to learn.)
It's also helpful to understand clearly that ns-front templates generate two types of files:
1. type files are files generated for particular data types in an app's hierarchy. That hierarchy is dynamically determined from an app.yml
file when nsfront makecode
is run. For instance, if an app uses watches, there may be a type watch
in the app.yml
file, and there may be multiple component files created for watches, included Watch.jsx
, Watches.jsx
and CreateWatchForm.jsx
.
2. standard files are always generated, regardless of specifics about the app. So for instance every app may contain a standard file client.js
.
A template is a directory containing the following:
- A
config.yml
file telling various configurations. - A general file template
generic.hbs
from which files for data are generated (see below). - a
fileTemplates
directory containing handlebars templates for the standard files. Files should have an.hbs
extension. You can create any number of subdirectories. - An optional
partials
directory containing handebars partials files. As with `fileTemplates, you can add any number of subdirectories. NsFront will read in your partials before generating files and you can make reference to them in your template files.
See our Sample Template.