dojo / cli-create-widget

Dojo - cli command for creating widgets boilerplate.

cli-create-widget

A Dojo CLI command that creates a Dojo 2 widget template with an optional custom element descriptor.

• Usage
• Features
• How do I contribute?
  • Code Style
  • Installation
  • Testing
• Licensing information

Usage

To use @dojo/cli-create-widget, install the project globally along side dojo cli:

npm install -g @dojo/cli-create-widget

Run using:

dojo create [widget] --name <widget name> --styles <CSS path> --tests <test path>

Features

@dojo/cli-create-widget generates an opinionated skeleton component structure for use within a Dojo 2 application. The location where styles and tests are created can be customized using the --styles and --tests arguments respectively. By default, the following folder structure will be created:

MyComponent.ts
styles/
styles/myComponent.m.css
styles/myComponent.m.css.d.ts,
tests/unit/MyComponent.ts

It's also possible to generate a Custom Element descriptor by passing the --component boolean argument. This will generate a widget that includes the @customElement decorator with an empty template object ready for configuration, please see the @dojo/widget-core readme for more information.

How do I contribute?

We appreciate your interest! Please see the Dojo 2 Meta Repository for the Contributing Guidelines.

Code Style

This repository uses prettier for code styling rules and formatting. A pre-commit hook is installed automatically and configured to run prettier against all staged files as per the configuration in the projects package.json.

An additional npm script to run prettier (with write set to true) against all src and test project files is available by running:

npm run prettier

Installation

To start working with this package, clone the repository and run npm install.

In order to build the project run grunt dev or grunt dist.

Testing

Test cases MUST be written using Intern using the Object test interface and Assert assertion interface.

90% branch coverage MUST be provided for all code submitted to this repository, as reported by istanbul’s combined coverage results for all supported platforms.

To test locally run:

grunt test

Licensing information

© 2018 JS Foundation. New BSD license.

cli-create-widget's Issues

Creating an element with a `-` fails to generate valid code

Bug

I was trying to create some custom elements and in doing so I ran

npx dojo create widget -c=true -n github-api

Unfortunately it doesn't strip out illegal characters and generated some invalid code:

/**
 * @type github-apiProperties
 *
 * Properties that can be set on github-api components
 */
export interface github-apiProperties { };

export const ThemedBase = ThemedMixin(WidgetBase);

@customElement({
	tag: 'dojo-github-api',
	attributes: [],
	properties: [],
	events: []
})
@theme(css)
export class github-api<P extends github-apiProperties = github-apiProperties> extends ThemedBase<P> {
	protected render(): DNode | DNode[] {
		return null;
	}
}

export default github-api;

Package Version: 0.6.2

Expected behavior:

I'd expect illegal characters to be stripped (especially dashes as I would expect this to be a common pattern). If no valid characters remains I'd expect the command to fail with an informative message. Alternatively, it'd be OK if invalid characters were converted to underscore.

Update Issue Template

Thank you for contributing to Dojo 2.

Our issue tracker is for bugs for Dojo 2.

Please make sure you have read our Contributing Guidelines
available at: https://github.com/dojo/meta/blob/master/CONTRIBUTING.md

For general questions and discussion, join us on Gitter.im at: https://gitter.im/dojo/dojo2

Improve configuration around directory defaults

I would like to better define where files are created with this tool. It should be possible to place configuration information regarding where tests and styles should go. However most of the use cases aren't served by the configuration and it requires rather verbose CLI commands (or capitulation by the user to the default style).

Here is the use case I'd like to support.

• Create a widget in a particular directory (e.g. src/widgets/user/view/UserView.ts).
• Tests are created in a known location relative to the widget directory root (e.g. test/unit/widgets/user/view/UserView.ts).
• I would like to place styles relative to the widget (e.g. src/widgets/user/view/styles/UserView.m.css) or relative to the application root with the hierarchy maintained (e.g. src/styles/widgets/user/view/UserView.m.css`).
• Optionally I would like to add a suffix to the tests (i.e. UserView.spec.ts)

#31 may have made some headway on this feature and #34 may add additional configuration considerations such as locales and nls directory options.

The separator in import clause should be '/'

Bug

When I use @dojo/cli-create-widget to generate a widget template,
the generated widget import clause is error

import * as css from './styles\container.m.css';

the test class also has the same error

import Container from './..\..\Container';

My pc is Windows 11

Generated widgets don't make use of relevant default exports

Enhancement

Widgets created via dojo create widget don't import appropriate default exports as defaults, for exampleWidgetBase.

Package Version: 5.0.0

dojo create widget --name MyComponentWidget --component

Expected behavior:

import { DNode } from '@dojo/framework/widget-core/interfaces';
import ThemedMixin, { theme } from '@dojo/framework/widget-core/mixins/Themed';
import WidgetBase from '@dojo/framework/widget-core/WidgetBase';

import customElement from '@dojo/framework/widget-core/decorators/customElement';
...

Actual behavior:

import { DNode } from '@dojo/framework/widget-core/interfaces';
import { ThemedMixin, theme } from '@dojo/framework/widget-core/mixins/Themed';
import { WidgetBase } from '@dojo/framework/widget-core/WidgetBase';

import { customElement } from '@dojo/framework/widget-core/decorators/customElement';
...

Publish a version of cli-create-widget

npm install -g @dojo/cli-create-widget currently fails because it has not yet had a version published to npm.

Repurpose command to create a full widget library scaffold

Proposal

Current the existing cli-create-widget command is used to create a single widget in a project (with test/css files etc), this is confusing as the cli-build-app provides a scaffold for a complete application project. With the new widget library build tooling, theme build tooling and dojo/parade we should consider repurposing this command to scaffold a complete widget library project.

This would provide symmetry with the cli-build-app command and I believe more valuable overall.

Doesn't work out-of-the-box

Bug

When installed globally, this breaks @dojo/cli's create function.

Package Version: 0.1.0

Code

$ npm install -g @dojo/cli
$ npm install -g @dojo/cli-create-widget
$ dojo create
Commands are not available: Error: Failed to load module /usr/local/lib/node_modules/@dojo/cli-create-widget
Nested error: Cannot find module '@dojo/cli-create-app/createDir'

Manually installing @dojo/cli-create-app globally resolves the issue.

Expected behavior:

dojo create should work

Actual behavior:

An error is emitted.

Package needs to be updated to point to @dojo/framework

This package should be updated to use the new @dojo/framework instead of the individual core, has, i18n, widget-core, routing, stores, and shim packages.

Use the render files implementation from the CLI helper

Enhancement

This can be removed:

cli-create-widget/src/run.ts

Line 6 in f11f0b2

import renderFiles from '@dojo/cli-create-app/renderFiles';

We can now use the helper method provided by the CLI! dojo/cli#180

Create various widget types

As a user there are several different widgets I commonly create

• a themed widget
• an internationalized widget
• an outlet style widget
• a container
• a provider

The themed widget is essentially what cli-create-widget makes now.

The internationalized widget would add a I18nMixin to the themed widget with a const messages in render; a root nls bundle, and nls bundles for any additional languages.

The outlet style widget is just a WidgetBase with outlets to other widgets. It would be wonderful it we could somehow pick up the routes from a route file and create missing widgets and the outlets and routes all in one command.

The container would contain an already created widget. It could maybe create the widget if it didn't exist.

The provider would be a WidgetBase with a Provider in the renderer maybe wrapping a widget.

I don't know if we need all of these widgets initially. But having better support for standard widget patterns would make this tool wonderful and instructive.

README review

• Remove the WARNING.
• The TOC needs to be updated.
• This is a comment for all @dojo READMEs... We are not consistent with how we specify the npm install command. Sometimes we use npm i and sometimes npm install'. This one uses npm install` which I think is the better choice.
• I would like to see a bit more info about the custom element descriptor. Explain what creating a custom element means in regards to the widget. Why would I want to create one? Explain how to use the custom element. Explain how many or how few Dojo 2 components does one need to load in an app to use the custom element. Maybe compare using a custom element versus the widget. How do I decide which way to go? Pros and cons. Stuff like that.