DEV Community: Jessy Jordan

What is a software blueprint?

Jessy Jordan — Sat, 17 Jul 2021 11:15:28 +0000

A software blueprint is a high-level plan or outline used in the development of software.

When the term blueprint is used in programming, it usually refers to one of two related, yet slightly different concepts:

a high-level, graphical or written piece of documentation of software architecture ("blueprint for humans")
a piece of code serving as a template for code-generating tools that build or configure applications ("blueprint for machines")

Overall, software blueprints are a powerful tool for planning, building and maintaining software projects.

And first, let's take a look into how software blueprints are used as documentation.

Blueprints as software design documentation

Blueprints may be used to design and document the architecture of applications. It serves as a high-level representation of software design that supports the development process in several ways:

As part of the planning process of upcoming feature work, a blueprint communicates implementation requirements across an engineering team more efficiently; a software architect may design a new feature and they can then use a blueprint to provide the feature requirements to the software engineers who will implement it later on.

In a similar manner, blueprints help teams consisting of both engineering and non-engineering professionals to collaborate on the development of business applications; blueprints empower stakeholders of either department to define requirements using common terminology that doesn't require in-depth, technical knowledge. This way, a software blueprinting process reduces the number of cycles needed for planning, implementing and iterating on features by getting application requirements defined well from the beginning. This in turn helps to reduce the overall development time of applications significantly.

Through this process, blueprints become an effective strategy for maintaining documentation of software architecture. As a business goes through the iterative process of blueprinting feature work upfront and implementing features according to the design, a growing documentation for the business's software architecture is created automatically.

Using Unified Modeling Language (UML) software architects oftentimes visualize the design of the systems they and their team are implementing. Many products and open-source tools support software design with UML, such as Papyrus, Visual Studio or Lucidchart.

For more insight into the rationale behind blueprints as documentation and UML specifically, you may want to continue reading "UmlAsBlueprint" by Martin Fowler.

But the term blueprint isn't only used to describe software design plans that help people to implement said software. "Blueprint" also refers to those design plans that help computers to implement software automatically.

Blueprints as automatic programming templates

In automatic programming a computer program, when run, generates code automatically based on a specific configuration. The configuration for these code generators can come from direct user input (e.g. parameters provided to a shell command) and - from blueprints.

As part of the code generation process, the blueprint outlines the layout and configuration of the resulting program. This makes the blueprint useful in scaffolding and extending applications; a software engineer who uses blueprints in their development process can focus on the implementation of the business logic itself and worry less about how their implementation fits into the code base.

Therefore when used as code generator templates, blueprints improve the immediate developer experience significantly and can reduce overall development time. Lastly, they facilitate scaling and maintaining large applications by making extending applications easier.

Many different tools and frameworks already support blueprints and code generators for developers. This includes, for example and among many others, the Python web framework Flask, the Blueprint visual scripting system of Unreal Engine, and the JavaScript framework EmberJS.

Blueprints as documentation and automatic programming tool

Blueprints are a powerful tool in planning, documenting and implementing software applications.

Blueprints - when used as documentation for software architecture - are critical for successfully planning and executing development cycles, whereas blueprints - when used as a template for code generators - are an integral part of maintaining and scaling code bases gracefully.

Have you created or used software blueprints before? Let me know in the comments below!

Why Blueprints in Ember Are Cool and How They Save You Time Writing Tests

Jessy Jordan — Sat, 10 Jul 2021 12:10:52 +0000

Developing and maintaining a growing front-end code base is complex on its own. And only sufficient test coverage will allow you to continue to build features with confidence and without the fear of critical regressions.

Therefore, automatic testing is an important part of your and your team's joint efforts to build web applications, including your Ember apps.

Still, writing tests can be time-consuming.

Despite powerful testing tools available in the JavaScript and Ember ecosystem today, and even considering that the framework already provides you a great foundation for testing, you might still need to spend some time defining your own project-specific test setup.

You may have written custom stubs and mocks for those services, network requests and third-party libraries that can't be easily simulated during your testing scenarios otherwise. And as your application grows, often the number of custom testing helpers you need to include in many, if not all, of your test files increases as well.

This in turn introduces a new entry barrier for developers who are new to the code base and who want to write their first test: Due to a lack of familiarity with all the project-specific configurations, they might either spend a lot of time trying to figure out what kind of setup to copy-paste from existing test files of your test suite into their own.

Or due to a lack of time, they might just avoid writing that test altogether.

Still, writing tests is important and should require you as little on-ramp time as possible - even as your application grows.

What if you could automate the project-specific setup of your tests, so you can focus on the actual work of writing the testing scenarios for your features instead of worrying about how to setup the test to begin with?

Fortunately, Ember CLI has you covered with tools to do exactly that.

But first, let's take a look into how test scaffolding in in Ember apps works in general, and secondly, how we can modify the process for our testing needs.

Easy Test Scaffolding with Generate Commands

Out of the box, the Ember CLI already provides you with several generate commands to get started with writing your tests.

This is how you would start off writing an application test for my-feature:

# create a pre-configured application test file for 'my-feature'
ember generate acceptance-test my-feature

Running this command in your shell will provide you with the following setup:

// tests/acceptance/my-feature-test.js

import { module, test } from 'qunit';
import { visit, currentURL } from '@ember/test-helpers';
import { setupApplicationTest } from 'ember-qunit';

module('Acceptance | my feature', function(hooks) {
  setupApplicationTest(hooks);

  test('visiting /my-feature', async function(assert) {
    await visit('/my-feature');

    assert.equal(currentURL(), '/my-feature');
  });
});

Check out the official Ember CLI Guides for more information on how to generate and use blueprints.

In the next step, you would usually start to modify the test file with your own custom testing setup, e.g. by invoking test utils you have written yourself or by importing methods from other testing libraries you frequently use.

Luckily, you don't need to do all of this work by hand.

Instead, you can automate this modification process and instruct the cli's generate command to create a custom test file, instead of the default one.

This is where Ember CLI blueprints come in.

Blueprints Define Your Testing Scaffold Layout

Anytime you run ember generate acceptance-test xyz, the cli will create your test file based on your command-line input and the framework blueprint that is associated with the acceptance-test parameter:

// blueprints/acceptance-test/qunit-rfc-232-files/tests/acceptance/__name__-test.js

import { module, test } from 'qunit';
import { visit, currentURL } from '@ember/test-helpers';
import { setupApplicationTest } from 'ember-qunit';

module('<%= friendlyTestName %>', function(hooks) {
  setupApplicationTest(hooks);

  test('visiting /<%= dasherizedModuleName %>', async function(assert) {
    await visit('/<%= dasherizedModuleName %>');

    assert.equal(currentURL(), '/<%= dasherizedModuleName %>');
  });
});

The configuration of the process itself, e.g. which naming convention to use to name your test modules, is done in the blueprint's index.js:

// blueprints/acceptance-test/index.js

'use strict';

const fs = require('fs');
const path = require('path');
const pathUtil = require('ember-cli-path-utils');
const stringUtils = require('ember-cli-string-utils');

const useTestFrameworkDetector = require('../test-framework-detector');

module.exports = useTestFrameworkDetector({
  description: 'Generates an acceptance test for a feature.',

  locals: function (options) {
    let testFolderRoot = stringUtils.dasherize(options.project.name());

    if (options.project.isEmberCLIAddon()) {
      testFolderRoot = pathUtil.getRelativeParentPath(options.entity.name, -1, false);
    }

    let destroyAppExists = fs.existsSync(
      path.join(this.project.root, '/tests/helpers/destroy-app.js')
    );

    let friendlyTestName = [
      'Acceptance',
      stringUtils.dasherize(options.entity.name).replace(/[-]/g, ' '),
    ].join(' | ');

    return {
      testFolderRoot: testFolderRoot,
      friendlyTestName,
      destroyAppExists,
    };
  },
});

And even better: You can also customize the default scaffolding by overriding existing blueprints.

By generating your own acceptance-test blueprint in your project, you can now extend this functionality with your own, custom acceptance test setup in a single generate command.

Writing Your Own Testing Blueprint for Your Ember App

To get started, you can use ember generate while in your Ember application's directory again:

ember generate blueprint acceptance-test

This should leave you with a new blueprint configuration file at blueprints/acceptance-test-index.js:

'use strict';

module.exports = {
  description: ''

  // locals(options) {
  //   // Return custom template variables here.
  //   return {
  //     foo: options.entity.options.foo
  //   };
  // }

  // afterInstall(options) {
  //   // Perform extra work here.
  // }
};

To create your own modified version of acceptance test blueprints, you can lend most of the framework's default setup for your specific test setup.

For a recent app, which uses QUnit and the latest Ember QUnit API, your index.js could look like this:

// blueprints/acceptance-test/index.js
'use strict';

const fs = require('fs');
const path = require('path');
const stringUtils = require('ember-cli-string-utils');

module.exports = {
  description: 'Generates an acceptance test for a feature.',

  locals: function (options) {
    let destroyAppExists = fs.existsSync(
      path.join(this.project.root, '/tests/helpers/destroy-app.js')
    );

    let friendlyTestName = [
      'Acceptance',
      stringUtils.dasherize(options.entity.name).replace(/[-]/g, ' '),
    ].join(' | ');

    return {
      testFolderRoot: 'tests/acceptance/',
      friendlyTestName,
      destroyAppExists,
    };
  },
};

Next, copy over the directory structure from the list of framework blueprints for your particular test setup into the a new blueprints/acceptance-test/files directory in your project, including the default template __name__-test.js.

We assume you're working with a recent Ember app using the latest Ember QUnit API in this example:

# copy from framework blueprints file layout...
-- qunit-rfc-232-files
    |-- tests
        |-- acceptance
            |-- __name__-test.js

# ...to your project's file layout
-- files
    |-- tests
        |-- acceptance
            |-- __name__-test.js

// blueprints/acceptance-test/files/tests/acceptance/__name__-test.js
import { module, test } from 'qunit';
import { visit, currentURL } from '@ember/test-helpers';
import { setupApplicationTest } from 'ember-qunit';

module('<%= friendlyTestName %>', function(hooks) {
  setupApplicationTest(hooks);

  test('visiting /<%= dasherizedModuleName %>', async function(assert) {
    await visit('/<%= dasherizedModuleName %>');

    assert.equal(currentURL(), '/<%= dasherizedModuleName %>');
  });
});

Now you can modify the template at blueprints/acceptance-test/files/tests/acceptance/__name__-test.js to your needs.

In this example, we want to ensure that in each new acceptance test file generated in the future, an additional helper util from our project is imported, that ember-sinon-qunit is setup correctly and - most importantly - that our module description sparkles ✨:

// blueprints/acceptance-test/files/tests/acceptance/__name__-test.js
import { module, test } from 'qunit';
import { visit, currentURL } from '@ember/test-helpers';
import { setupApplicationTest } from 'ember-qunit';
import { sinon } from 'sinon';

import { setupStripe } from 'my-ember-app/tests/helpers/stripe-mock';

module('<%= friendlyTestName %> ✨✨✨', function(hooks) {
  setupApplicationTest(hooks);
  setupStripe(hooks);

  hooks.beforeEach(function() {
    this.testStub = sinon.stub();
  });

  test('visiting /<%= dasherizedModuleName %>', async function(assert) {
    await visit('/<%= dasherizedModuleName %>');

    assert.equal(currentURL(), '/<%= dasherizedModuleName %>');
  });
});

Finally, if we run the generate command for creating an acceptance test again, the cli will use our custom testing blueprint configuration and modify our test file accordingly. Check it out:

ember generate acceptance-test my-feature

// tests/acceptance/my-feature-test.js
import { module, test } from 'qunit';
import { visit, currentURL } from '@ember/test-helpers';
import { setupApplicationTest } from 'ember-qunit';
import { sinon } from 'sinon';

import { setupStripe } from 'my-ember-app/tests/helpers/stripe-mock';

module('Acceptance | my feature ✨✨✨', function(hooks) {
  setupApplicationTest(hooks);
  setupStripe(hooks);

  hooks.beforeEach(function() {
    this.testStub = sinon.stub();
  });

  test('visiting /my-feature', async function(assert) {
    await visit('/my-feature');

    assert.equal(currentURL(), '/my-feature');
  });
});

Now you're all set to start testing with one single command!

Improve Your Developer Experience with Ember and Custom Blueprints

You can save yourself and your team time by automating the setup of your test files leveraging blueprints in Ember.

Blueprints allow you to override the templates for existing testing generate commands, such as ember generate acceptance-test or ember generate component-test.

Beyond the scope of testing and which generate commands the framework already offers, you can add your own generate commands, too. If you always wanted to make it easier to write documentation for your project, why not create a ember generate docs blueprint today?

Jessy is a Senior Frontend Engineer at Meroxa, a public speaker and an organizer of the EmberJS Berlin meetup. Also, if you're into design, devops or data engineering, come join us!

The difference between ember serve and npm run start

Jessy Jordan — Sun, 27 Jun 2021 14:16:42 +0000

The difference between `ember serve` and `npm run start`

When you have built a single-page-application using Ember CLI, you have two options for starting your app locally. You can either use the CLI's ember serve command directly or you can use the handy npm alias that is created for you after generating a new Ember app: npm run start

But what's the difference between those two?

What `npm run start` is used for

First, npm run start allows you to create your own default boot up command for your application by e.g. passing additional parameters to ember serve and hide this modified booting instruction away in one, single, shorthand command via a definition in your package.json. This makes you type less and can make your life easier when developing your app locally.

If you want to learn more about how to modify the ember serve command, check out the official Ember CLI Docs.

In a fresh Ember app though, the functionality of both ember serve and npm run start will be almost identical. Emphasis on almost.

Sometimes `ember serve` and `npm run start` don't behave the same way

Recently, while working on one of my side projects, I tried to boot up an Ember application using TailwindCSS by running the ember serve command. The build process was kicked off, but ultimately failed with the following error message:

Object.entries(...).flatMap is not a function

The stack trace pointed to issues with the PostCSS compiler I had been using to integrate TailwindCSS with my app's styles:

Object.entries(...).flatMap is not a function
    at PostcssCompiler.Plugin (/home/jayjayjpg/Documents/projects/my/project/node_modules/broccoli-plugin/index.js:7:31)
    at new CachingWriter (/home/jayjayjpg/Documents/projects/my/project/node_modules/broccoli-caching-writer/index.js:18:10)
    at new PostcssCompiler (/home/jayjayjpg/Documents/projects/my/project/node_modules/broccoli-postcss-single/index.js:20:5)
    at Object.keys.map (/home/jayjayjpg/Documents/projects/my/project/node_modules/ember-cli-postcss/index.js:36:12)
// ...

After some debugging and double-checking my setup that I have followed from Chris Masters' working example for TailwindCSS in an Ember app in my ember-cli-build.js was correct:

// ember-cli-build.js
'use strict';

const EmberApp = require('ember-cli/lib/broccoli/ember-app');
const isProduction = EmberApp.env() === 'production';

const purgeCSS = {
  module: require('@fullhuman/postcss-purgecss'),
  options: {
    content: [
      // add extra paths here for components/controllers which include tailwind classes
      './app/index.html',
      './app/templates/**/*.hbs',
      './app/components/**/*.hbs'
    ],
    defaultExtractor: content => content.match(/[A-Za-z0-9-_:/]+/g) || []
  }
}

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    postcssOptions: {
      compile: {
        plugins: [
          {
            module: require('postcss-import'),
            options: {
              path: ['node_modules']
            }
          },
          require('tailwindcss')('./app/tailwind.config.js'),
          ...isProduction ? [purgeCSS] : []
        ]
      }
    }
  });
  return app.toTree();
};

...I started to do a quick google search, to see if any other folks using TailwindCSS ran into a similar issue.

And indeed, I found a couple of issues here and there that pointed to the fact, that the .flatMap method used at build time of my application was a more recent feature of Node and only available from Node v11+.

I confirmed that I was still on an older version of Node, that this would explain the lacking support of the .flatMap function:

node -v
10.16.3

...and was enthusiastic about quickly resolving the build problem with an upgrade of Node. Since I was using nvm my upgrade turned out as follows:

nvm install 14
nvm use 14
rm -rf node_modules/ && npm install

As soon as the installation finished, I tried my luck again by running ember serve, and to my surprise - the build failed again with the very same .flatMap is not a function error!

Still in disbelief, I tried running npm run start instead and lo and behold - my app built successfully?

How could my application build fail when the build command was run directly, but still succeed when its alias was executed?

How Node, NVM and Ember CLI work together

Once I checked on the versions of my Ember CLI and my Node installs, it became more clear, why npm run start and ember serve would behave differently:

node -v
v14.17.1

ember -v
ember-cli: 3.26.1
node: 10.16.3
os: linux x64

How come that Ember CLI was linked to an older version of Node different from my local Node version?

In my case, I've been using nvm to switch between different versions of Node on my machine.

When using nvm, it's important to be mindful on how this will affect the usage of globally installed packages. Nvm ensures that any global installs of binaries end up in a dedicated, versioned directory of nvm in the user's HOME directory. On Linux, you can verify this by checking the Ember CLI's binary location as follows:

whereis ember
ember: /home/jayjayjpg/.nvm/versions/node/v10.16.3/bin/ember

A while ago I had installed Ember CLI globally via npm install -g ember-cli while on Node 10.16.3. This instructed nvm to store the binary in the related 10.16.3 Node directory and make it available via this Node version. Now whenever I would run ember serve on my command line, this outdated binary would be used, running on Node 10.16.3, regardless if I had instructed nvm to switch to Node v.14.17.1 or not:

# Switching to Node 10.16.3
nvm use 10

node -v
v10.16.3

ember -v
node: 10.16.3

# Switching to Node 14.17.1
nvm use 14

node -v
v14.17.1

ember -v
node: 10.16.3

Whenever I would run npm run start though, my project's local Ember CLI version would be used leading to a successful app build.

The behavior of ember serve and npm run start doesn't have to differ this way though, as nvm provides you with a command to migrate all of your already existing, global npm installations over to a newer version of Node and make them available when switching to said version:

nvm install 14 --reinstall-packages-from=10

After the migration I could now see my global Ember CLI binary associated with the newer Node version and residing in the path that I'd expect:

whereis ember
ember: /home/jayjayjpg/.nvm/versions/node/v14.17.1/bin/ember

ember -v
ember-cli: 3.26.1
node: 14.17.1

And finally, upon running ember serve, the app would build successfully using Node v.14.17.1 just as it would using npm run start!

So what's the difference between `ember serve` and `npm run start`?

In a fresh Ember app and in nearly all cases, npm run start and ember serve function the exact same way. But if you have a different version of Ember CLI installed globally versus locally or if you're using version managers for Node, the outcome of these two commands may differ from each other.

This post has been inspired by this great response on Stackoverflow to the question "Is there a difference between ember serve and npm start?"

DEV Community: Jessy Jordan

What is a software blueprint?

Blueprints as software design documentation

Blueprints as automatic programming templates

Blueprints as documentation and automatic programming tool

Why Blueprints in Ember Are Cool and How They Save You Time Writing Tests

Easy Test Scaffolding with Generate Commands

Blueprints Define Your Testing Scaffold Layout

Writing Your Own Testing Blueprint for Your Ember App

Improve Your Developer Experience with Ember and Custom Blueprints

The difference between ember serve and npm run start

The difference between ember serve and npm run start

What npm run start is used for

Sometimes ember serve and npm run start don't behave the same way

How Node, NVM and Ember CLI work together

So what's the difference between ember serve and npm run start?

The difference between `ember serve` and `npm run start`

What `npm run start` is used for

Sometimes `ember serve` and `npm run start` don't behave the same way

So what's the difference between `ember serve` and `npm run start`?